include/javascript/jquery/jquery.elementReady.js

   1 /* jQuery elementReady plugin
   2  * Version 0.6
   3  * Copyright (C) 2007-08 Bennett McElwee.
   4  * Licensed under a Creative Commons Attribution-Share Alike 3.0 Unported License (http://creativecommons.org/licenses/by-sa/3.0/)
   5  * Permissions beyond the scope of this license may be available at http://www.thunderguy.com/semicolon/.
   6  */
   7
   8 /*
   9         IMPLEMENTATION NOTES
  10         There may be race conditions. The most likely could occur if check() is
  11         called while a previous invocation of check() is still running. This could
  12         cause a callback to be called more than once, or not at all. Less likely is
  13         for elementReady() to be called concurrently with check() (with similar
  14         effects) or with itself (which could cause an interval to run forever).
  15         None of these are likely to occur. In fact I don't think they are possible
  16         at all except on IE. -- Bennett McElwee, August 2007
  17 */
  18 (function($) {
  19
  20 /**
  21  * While a page is loading, call a given callback function as soon as a specific
  22  * element (with a specific ID) is loaded into the DOM, even before the full DOM
  23  * has been loaded. Executes the function within the context of the element. This
  24  * means that when the passed-in function is executed, the 'this' keyword points
  25  * to the specific DOM element.
  26  *
  27  * The function returns 'this', so you can chain multiple calls to
  28  * elementReady(). (Not that there's much benefit in doing that.)
  29  *
  30  * One argument is passed to the callback: a reference to the jQuery function.
  31  * You can name this argument $ and therefore use the $ alias even in
  32  * noConflict mode.
  33  *
  34  * If the element has not been found by the time the DOM is fully loaded, then
  35  * the function will not be called.
  36  *
  37  * The function works by polling the DOM at short intervals. By default it polls
  38  * every 23 milliseconds, but you can change this by setting
  39  * $.elementReady.interval_ms to whatever value you like.
  40  * Don't bother changing this unless you really know what you're doing.
  41  *
  42  * @example
  43  * $.elementReady('powerpic', function(){
  44  *     this.src = 'powered-by-jquery.png';
  45  * });
  46  * @desc Change the source of a specific image as soon as it is loaded into the
  47  * DOM (before the whole DOM is loaded).
  48  *
  49  * @example
  50  * $.elementReady('header', function(){
  51  *     $(this).addClass('fancy');
  52  * });
  53  * @desc If you want to have the jQuery object instead of the regular DOM
  54  * element, use the $(this) function.
  55  *
  56  * @example
  57  * $.elementReady('first',  function(){ $(this).fancify(); })
  58  *  .elementReady('second', function(){ $(this).fancify(); });
  59  * @desc Chain multiple calls to $.elementReady().
  60  *
  61  * @example
  62  * jQuery.noConflict();
  63  * jQuery.elementReady('header', function($){
  64  *     $(this).addClass('fancy');
  65  * });
  66  * @desc Use the '$' alias within your callback, even in noConflict mode.
  67  *
  68  * @example
  69  * $.elementReady.interval_ms = 100;
  70  * @desc Change the polling interval to 100ms. This only works if $.elementReady()
  71  * has not yet been called.
  72  *
  73  * @name   $.elementReady
  74  * @type   jQuery
  75  * @param  String   id  string ID of the element to wait for
  76  * @param  Function fn  function to call when the element is ready
  77  * @return jQuery
  78  * @cat    Plugins/Event
  79  * @author Bennett McElwee
  80  */
  81 var interval = null;
  82 var checklist = [];
  83
  84 $.elementReady = function(id, fn) {
  85         checklist.push({id: id, fn: fn});
  86         if (!interval) {
  87                 interval = setInterval(check, $.elementReady.interval_ms);
  88         }
  89         return this;
  90 };
  91
  92 // Plugin settings
  93 $.elementReady.interval_ms = 23; // polling interval in ms
  94
  95 // Private function
  96 function check() {
  97         var docReady = $.isReady; // check doc ready first; thus ensure that check is made at least once _after_ doc is ready
  98         for (var i = checklist.length - 1; 0 <= i; --i) {
  99                 var el = document.getElementById(checklist[i].id);
 100                 if (el) {
 101                         var fn = checklist[i].fn; // first remove from checklist, then call function
 102                         checklist[i] = checklist[checklist.length - 1];
 103                         checklist.pop();
 104                         fn.apply(el, [$]);
 105                 }
 106         }
 107         if (docReady) {
 108                 clearInterval(interval);
 109                 interval = null;
 110         }
 111 };
 112
 113 })(jQuery);