diff options
| -rw-r--r-- | HISTORY.md | 1 | ||||
| -rw-r--r-- | README.md | 23 | ||||
| -rw-r--r-- | jquery.once.js | 46 | ||||
| -rw-r--r-- | package.json | 3 |
4 files changed, 56 insertions, 17 deletions
@@ -2,6 +2,7 @@ ## v2.0.0-alpha.5 October 5, 2014 - Added findOnce() to allow filtering once'd elements +- Added inline JavaScript code documentation ## v2.0.0-alpha.4 October 4, 2014 - Updated documentation @@ -27,7 +27,6 @@ Act on jQuery elements only once. Filters out all elements that had the same filter applied on them before. It can be used to ensure that a function is only applied once to an element. -<!-- /DESCRIPTION --> <!-- INSTALL/ --> @@ -59,6 +58,8 @@ be used to ensure that a function is only applied once to an element. ## Usage +### `.once()` + ``` javascript $('div.calendar').once('calendar', function() { // This function is only executed once for each div, even if this @@ -83,7 +84,10 @@ $('div.calendar').once(function() { }); ``` -To find once'd elements later on, use the `.findOnce()` function: +### `.findOnce()` + +After `.once()` is used and you need to retrieve all elements that have already +been executed with `.once()`, you can use the `.findOnce() function: ``` javascript $('div.calendar').findOnce('calendar', function() { @@ -92,6 +96,17 @@ $('div.calendar').findOnce('calendar', function() { }); ``` +### `.removeOnce()` + +It is possible to remove the `.once()` data, and iterate through each element +whose once state is removed: + +``` javascript +$('div.calendar').removeOnce('calendar', function() { + // This function is called for each element whose once() data is removed. +}); +``` + ## Development @@ -111,6 +126,10 @@ Update project documentation with [Projectz](https://github.com/bevry/projectz): npm run-script projectz +Generate code documentation with [JSDoc](http://usejsdoc.org): + + npm run-script jsdoc + <!-- HISTORY/ --> diff --git a/jquery.once.js b/jquery.once.js index 9ec9479..5361c74 100644 --- a/jquery.once.js +++ b/jquery.once.js @@ -1,10 +1,21 @@ /*! - * jQuery Once Plugin 2.0.0-alpha.5 - * http://github.com/robloach/jquery-once + * @file jQuery Once + * @description Act on jQuery elements only once. + * @version 2.0.0-alpha.5 + * @link http://github.com/robloach/jquery-once * - * Dual licensed under the MIT and GPL licenses: - * http://www.opensource.org/licenses/mit-license.php - * http://www.gnu.org/licenses/gpl.html + * @example + * // Change the color to green only once. + * $('p').once('changecolor', function() { + * $(this).css('color', 'green'); + * }); + * + * @see once + * @see removeOnce + * @see findOnce + * + * @author Rob Loach (http://robloach.net) + * @license MIT, GPL-2.0 */ (function (factory) { @@ -23,7 +34,7 @@ /** * Filters elements by whether they have not yet been processed. * - * @param id + * @param {(string|function)} [id] * (Optional) If this is a string, then it will be the data ID used * to determine whether it has already been processed or not. * @@ -34,14 +45,16 @@ * When the id is neither a string or a function, it becomes a unique * identifier, depicted as a number. The element's data ID will then be * represented in the form of "jquery-once-#". - * @param fn + * @param {function} [fn] * (Optional) If given, this function will be called for each element that * has not yet been processed. The function's return value follows the same * logic as $.each(). Returning true will continue to the next matched * element in the set, while returning false will entirely break the * iteration. + * @returns jQuery element collection of elements that have now run once. * - * @api public + * @public + * @global */ $.fn.once = function (id, fn) { if (typeof id !== 'string') { @@ -68,19 +81,22 @@ /** * Removes the once data from the given elements, based on the given ID. * - * @param id + * @param {string} id * A required string representing the name of the data id which should be used * when filtering the elements. This only filters elements that have already * been processed by the once function. The id should be the same id that * was originally passed to the once() function. - * @param fn + * @param {function} [fn] * (Optional) If given, this function will be called for each element that * whose element's once data was removed. The function's return value * follows the same logic as $.each(). Returning true will continue to the * next matched element in the set, while returning false will entirely * break the iteration. + * @returns jQuery element collection of elements that now have their once + * data removed. * - * @api public + * @public + * @global */ $.fn.removeOnce = function (id, fn) { // Filter through the elements to find the once'd elements. @@ -95,19 +111,21 @@ /** * Filters elements that have already been processed once. * - * @param id + * @param {string} id * A required string representing the name of the data id which should be used * when filtering the elements. This only filters elements that have already * been processed by the once function. The id should be the same id that * was originally passed to the once() function. - * @param fn + * @param {function} [fn] * (Optional) If given, this function will be called for each element that * has not yet been processed. The function's return value follows the same * logic as $.each(). Returning true will continue to the next matched * element in the set, while returning false will entirely break the * iteration. + * @returns jQuery element collection of elements that have been run once. * - * @api public + * @public + * @global */ $.fn.findOnce = function (id, fn) { // Filter the elements by which do have the data. diff --git a/package.json b/package.json index d10985e..fedaa8a 100644 --- a/package.json +++ b/package.json @@ -58,6 +58,7 @@ "scripts": { "test": "grunt jshint qunit", "projectz": "node_modules/.bin/projectz compile", - "release": "grunt release" + "release": "grunt release", + "jsdoc": "npm install jsdoc && node_modules/.bin/jsdoc jquery.once.js" } } |