The plugins site is currently in development.
We've been looking to provide a higher-quality, spam-free experience at the plugins site for some time, and a major error on our part forced us to shut down the current site before we could put the new one in place. We are developing a new site, and you can follow along with its development on GitHub. For more information about this transition, including steps you can take as a plugin author to prepare, please read our post about what's going on.
jQuery available Plugin
jQuery available Plugin - Faster Than Domready
The jQuery available Plugin provides a faster alternative to using $(document).ready() when you need to manipulate a single element the instant it becomes available (before the DOM is even fully loaded). This is useful if you want to avoid DOM flicker, especially if your document contains a lot of nodes (which can slow the domready event significantly). Using $.available(), any changes you make to an element will be visible to the user the instant they are rendered in the browser (turbo mode will need to be used in certain cases, see below).
The usage is exactly the same as the $.ready() function, except instead of passing the document object, you simply pass a selector. This will execute a function within the context of the first matched element. You could pass an id, class, or tag (even the body tag itself). See examples below...
Turbo Mode
The default behavior of $.available() is to check if the targeted element exists, and also if the next element on the page has begun to load. This ensures that the targeted element is completely finished loading. With $.append(), for example, this check needs to be in place or else the appended HTML could end up not being the last item in the targeted node. In certain cases however, like targeting the body tag or a div with lots of nodes in it, this will force $.available() to wait until the DOM is ready (since there is no element after the body) or the heavy node is finished. This defeats the purpose of the plugin.
The solution for this is Turbo Mode (as of 1.5.x). This will instruct $.available() to only check if the target element has begun to load (the opening tag exists). This is strongly recommended when prepending to an element, especially the body tag or a heavy div containing lots of nodes.
Usage
$( elem ).available( fn , [turbo] );
Examples
If you wanted to change the text color of your header div right away:
$('#header').available(function(){
$(this).css('color','#fff');
});If you wanted to prepend something to the body of your document and have it appear instantly (like a roadblocking lightbox):
$('body').available(function(){
$(this).prepend('<div>some html</div>');
},true);IMPORTANT: In the above case Turbo Mode should be used, or else there will be no speed gains over $.ready().
Notes
- The $.available() function is intended to behave exactly like the other jQuery event helpers. You may call $.available() as many times as you need to on any set of elements and the functions will then be executed in the order they were defined, grouped by each unique element's availability. This means that if you called one() and two() on the last div of the page and three() and four() on the first div, they would execute three(), four(), one(), two() if there was a long delay between the first and last div loading. Within the context of each unique element however, the functions will always be called in the order they were defined.
- The $.available() function will only work on the first matched element. This is because in the case of classes or tags, it would need to wait for the entire document to load in order to guarantee a match on every element. This would defeat the purpose of this plugin and in this case it would probably be better to use ready(). You would most likely use available() with either an id or the body tag (as demonstrated above). It is possible to to add logic to the plugin to treat unique elements (like an id) different from, say, classes or tags to enable on-the-fly manipulation of an unpredictable number of elements. This may be addressed in a later version...
- The available() function will stop polling when the function queue is empty or the DOM is ready. However, you can call it again anytime and it will restart, even after the DOM is fully loaded (in which case it will execute just once).
- Don't worry about calling available() on a non-existent element. The polling will be canceled once the DOM is ready and the element was not found.
- New in 1.5: If the function that is passed to $.available() contains errors, it will be skipped and logged to the console (if enabled). The rest of the queue will continue to execute normally. Previously this would cause $.available() to crash and the polling would run forever.
- Tested on Firefox 3.5; Safari 4; IE6,7,8; Chrome 3 (PC).
- I'd like to thank Bennett McElwee and his plugin elementReady for some helpful insights into solving this problem. http://www.thunderguy.com/semicolon/2007/08/14/elementready-jquery-plugin/
