1 /* jQuery elementReady plugin
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/.
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
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.
27 * The function returns 'this', so you can chain multiple calls to
28 * elementReady(). (Not that there's much benefit in doing that.)
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
34 * If the element has not been found by the time the DOM is fully loaded, then
35 * the function will not be called.
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.
43 * $.elementReady('powerpic', function(){
44 * this.src = 'powered-by-jquery.png';
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).
50 * $.elementReady('header', function(){
51 * $(this).addClass('fancy');
53 * @desc If you want to have the jQuery object instead of the regular DOM
54 * element, use the $(this) function.
57 * $.elementReady('first', function(){ $(this).fancify(); })
58 * .elementReady('second', function(){ $(this).fancify(); });
59 * @desc Chain multiple calls to $.elementReady().
62 * jQuery.noConflict();
63 * jQuery.elementReady('header', function($){
64 * $(this).addClass('fancy');
66 * @desc Use the '$' alias within your callback, even in noConflict mode.
69 * $.elementReady.interval_ms = 100;
70 * @desc Change the polling interval to 100ms. This only works if $.elementReady()
71 * has not yet been called.
73 * @name $.elementReady
75 * @param String id string ID of the element to wait for
76 * @param Function fn function to call when the element is ready
79 * @author Bennett McElwee
84 $.elementReady = function(id, fn) {
85 checklist.push({id: id, fn: fn});
87 interval = setInterval(check, $.elementReady.interval_ms);
93 $.elementReady.interval_ms = 23; // polling interval in ms
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);
101 var fn = checklist[i].fn; // first remove from checklist, then call function
102 checklist[i] = checklist[checklist.length - 1];
108 clearInterval(interval);