2 * jQuery Once v2.2.0 - http://github.com/robloach/jquery-once
3 * @license MIT, GPL-2.0
4 * http://opensource.org/licenses/MIT
5 * http://opensource.org/licenses/GPL-2.0
9 * Universal Module Definition
11 * jQuery Once has a dependency on jQuery, so we wrap the code with a UMD
12 * pattern in order to allow loading jQuery and jQuery Once through a module
13 * definition like CommonJS, AMD, or through a global object.
15 * @see {@link http://github.com/umdjs/umd}
20 if (typeof exports === 'object') {
22 factory(require('jquery'));
23 } else if (typeof define === 'function' && define.amd) {
26 define(['jquery'], factory);
36 * Ensures that the given ID is valid, returning 'once' if one is not given.
38 * @param {string} [id=once]
39 * A string representing the ID to check. Defaults to `'once'`.
41 * @returns The valid ID name.
43 * @throws TypeError when an ID is provided, but not a string.
46 var checkId = function (id) {
48 if (typeof id !== 'string') {
49 throw new TypeError('The jQuery Once id parameter must be a string');
55 * Filter elements that have yet to be processed by the given data ID.
57 * @param {string} [id=once]
58 * The data ID used to determine whether the given elements have already
59 * been processed or not. Defaults to `'once'`.
61 * @returns jQuery collection of elements that have now run once by
66 * // The following will change the color of each paragraph to red, just once
67 * // for the 'changecolor' key.
68 * $('p').once('changecolor').css('color', 'red');
70 * // .once() will return a set of elements that yet to have the once ID
71 * // associated with them. You can return to the original collection set by
74 * .once('changecolorblue')
75 * .css('color', 'blue')
77 * .css('color', 'red');
79 * // To execute a function on the once set, you can use jQuery's each().
80 * $('div.calendar').once().each(function () {
81 * // Since there is no once ID provided here, the key will be 'once'.
92 $.fn.once = function (id) {
93 // Build the jQuery Once data name from the provided ID.
94 var name = 'jquery-once-' + checkId(id);
96 // Find elements that don't have the jQuery Once data applied to them yet.
97 return this.filter(function () {
98 return $(this).data(name) !== true;
103 * Removes the once data from elements, based on the given ID.
105 * @param {string} [id=once]
106 * A string representing the name of the data ID which should be used when
107 * filtering the elements. This only filters elements that have already been
108 * processed by the once function. The ID should be the same ID that was
109 * originally passed to the once() function. Defaults to `'once'`.
111 * @returns jQuery collection of elements that were acted upon to remove their
116 * // Remove once data with the 'changecolor' ID. The result set is the
117 * // elements that had their once data removed.
118 * $('p').removeOnce('changecolor').css('color', '');
120 * // Any jQuery function can be performed on the result set.
121 * $('div.calendar').removeOnce().each(function () {
122 * // Remove the calendar behavior.
132 $.fn.removeOnce = function (id) {
133 // Filter through the elements to find the once'd elements.
134 return this.findOnce(id).removeData('jquery-once-' + checkId(id));
138 * Filters elements that have already been processed once.
140 * @param {string} [id=once]
141 * A string representing the name of the data id which should be used when
142 * filtering the elements. This only filters elements that have already
143 * been processed by the once function. The id should be the same id that
144 * was originally passed to the once() function. Defaults to 'once'.
146 * @returns jQuery collection of elements that have been run once.
150 * // Find all elements that have been changecolor'ed once.
151 * $('p').findOnce('changecolor').each(function () {
152 * // This function is called for all elements that has already once'd.
155 * // Find all elements that have been acted on with the default 'once' key.
156 * $('p').findOnce().each(function () {
157 * // This function is called for all elements that have been acted on with
158 * // a 'once' action.
168 $.fn.findOnce = function (id) {
169 // Filter the elements by which do have the data.
170 var name = 'jquery-once-' + checkId(id);
172 return this.filter(function () {
173 return $(this).data(name) === true;