defectivebydesign.org/20121205/files/misc/jquery.once.js

   1
   2 /**
   3  * jQuery Once Plugin v1.2
   4  * http://plugins.jquery.com/project/once
   5  *
   6  * Dual licensed under the MIT and GPL licenses:
   7  *   http://www.opensource.org/licenses/mit-license.php
   8  *   http://www.gnu.org/licenses/gpl.html
   9  */
  10
  11 (function ($) {
  12   var cache = {}, uuid = 0;
  13
  14   /**
  15    * Filters elements by whether they have not yet been processed.
  16    *
  17    * @param id
  18    *   (Optional) If this is a string, then it will be used as the CSS class
  19    *   name that is applied to the elements for determining whether it has
  20    *   already been processed. The elements will get a class in the form of
  21    *   "id-processed".
  22    *
  23    *   If the id parameter is a function, it will be passed off to the fn
  24    *   parameter and the id will become a unique identifier, represented as a
  25    *   number.
  26    *
  27    *   When the id is neither a string or a function, it becomes a unique
  28    *   identifier, depicted as a number. The element's class will then be
  29    *   represented in the form of "jquery-once-#-processed".
  30    *
  31    *   Take note that the id must be valid for usage as an element's class name.
  32    * @param fn
  33    *   (Optional) If given, this function will be called for each element that
  34    *   has not yet been processed. The function's return value follows the same
  35    *   logic as $.each(). Returning true will continue to the next matched
  36    *   element in the set, while returning false will entirely break the
  37    *   iteration.
  38    */
  39   $.fn.once = function (id, fn) {
  40     if (typeof id != 'string') {
  41       // Generate a numeric ID if the id passed can't be used as a CSS class.
  42       if (!(id in cache)) {
  43         cache[id] = ++uuid;
  44       }
  45       // When the fn parameter is not passed, we interpret it from the id.
  46       if (!fn) {
  47         fn = id;
  48       }
  49       id = 'jquery-once-' + cache[id];
  50     }
  51     // Remove elements from the set that have already been processed.
  52     var name = id + '-processed';
  53     var elements = this.not('.' + name).addClass(name);
  54
  55     return $.isFunction(fn) ? elements.each(fn) : elements;
  56   };
  57
  58   /**
  59    * Filters elements that have been processed once already.
  60    *
  61    * @param id
  62    *   A required string representing the name of the class which should be used
  63    *   when filtering the elements. This only filters elements that have already
  64    *   been processed by the once function. The id should be the same id that
  65    *   was originally passed to the once() function.
  66    * @param fn
  67    *   (Optional) If given, this function will be called for each element that
  68    *   has not yet been processed. The function's return value follows the same
  69    *   logic as $.each(). Returning true will continue to the next matched
  70    *   element in the set, while returning false will entirely break the
  71    *   iteration.
  72    */
  73   $.fn.removeOnce = function (id, fn) {
  74     var name = id + '-processed';
  75     var elements = this.filter('.' + name).removeClass(name);
  76
  77     return $.isFunction(fn) ? elements.each(fn) : elements;
  78   };
  79 })(jQuery);