diff options
| -rw-r--r-- | README.md | 41 | ||||
| -rw-r--r-- | component.json | 10 | ||||
| -rw-r--r-- | composer.json | 12 | ||||
| -rw-r--r-- | jquery.once.js | 79 |
4 files changed, 140 insertions, 2 deletions
@@ -1,4 +1,41 @@ -jquery-once +jQuery Once =========== -jQuery Once Plugin, originally from http://plugins.jquery.com/project/once
\ No newline at end of file +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. + +Usage +----- + +``` javascript +$('div.calendar').once('calendar', function() { + // This function is only executed once for each div, even if this + // code segment is executed repeatedly. +}); +$('div.calendar').once('calendar').click(function() { + // .once('calendar') filters out all elements which already have the + // class 'calendar'. It applies that class to the remaining elements + // and leaves them in the jQuery object. + // The previous set of elements can be restored with .end() +}); +``` + +It also works without supplying a name: + +``` javascript +$('div.calendar').once(function() { + // This function is only executed once for each div, even if this + // code segment is executed repeatedly. Other scripts can't refer + // to this `once` method and the class names used are in the form + // of jquery-once-1 and so on. +}); +``` + +License +------- + +Dual licensed under the MIT and GPL licenses. + +Credits +------- + +Written by Konstantin Käfer. diff --git a/component.json b/component.json new file mode 100644 index 0000000..c41c51c --- /dev/null +++ b/component.json @@ -0,0 +1,10 @@ +{ + "name": "jquery-once", + "description": "jQuery Once Plugin", + "version": "1.2.0", + "keywords": ["jquery"], + "dependencies": { + "component/jquery": "*" + }, + "scripts": ["jquery.once.js"] +} diff --git a/composer.json b/composer.json new file mode 100644 index 0000000..fcbe1f6 --- /dev/null +++ b/composer.json @@ -0,0 +1,12 @@ +{ + "name": "robloach/jquery-once", + "description": "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.", + "type": "component", + "license": [ + "MIT", + "GPL-2.0" + ], + "require": { + "components/jquery": "*" + } +} diff --git a/jquery.once.js b/jquery.once.js new file mode 100644 index 0000000..506fb48 --- /dev/null +++ b/jquery.once.js @@ -0,0 +1,79 @@ + +/** + * jQuery Once Plugin v1.2 + * http://plugins.jquery.com/project/once + * + * Dual licensed under the MIT and GPL licenses: + * http://www.opensource.org/licenses/mit-license.php + * http://www.gnu.org/licenses/gpl.html + */ + +(function ($) { + var cache = {}, uuid = 0; + + /** + * Filters elements by whether they have not yet been processed. + * + * @param id + * (Optional) If this is a string, then it will be used as the CSS class + * name that is applied to the elements for determining whether it has + * already been processed. The elements will get a class in the form of + * "id-processed". + * + * If the id parameter is a function, it will be passed off to the fn + * parameter and the id will become a unique identifier, represented as a + * number. + * + * When the id is neither a string or a function, it becomes a unique + * identifier, depicted as a number. The element's class will then be + * represented in the form of "jquery-once-#-processed". + * + * Take note that the id must be valid for usage as an element's class name. + * @param 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. + */ + $.fn.once = function (id, fn) { + if (typeof id != 'string') { + // Generate a numeric ID if the id passed can't be used as a CSS class. + if (!(id in cache)) { + cache[id] = ++uuid; + } + // When the fn parameter is not passed, we interpret it from the id. + if (!fn) { + fn = id; + } + id = 'jquery-once-' + cache[id]; + } + // Remove elements from the set that have already been processed. + var name = id + '-processed'; + var elements = this.not('.' + name).addClass(name); + + return $.isFunction(fn) ? elements.each(fn) : elements; + }; + + /** + * Filters elements that have been processed once already. + * + * @param id + * A required string representing the name of the class 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 + * (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. + */ + $.fn.removeOnce = function (id, fn) { + var name = id + '-processed'; + var elements = this.filter('.' + name).removeClass(name); + + return $.isFunction(fn) ? elements.each(fn) : elements; + }; +})(jQuery); |