Skip to content

Latest commit

 

History

History
94 lines (55 loc) · 3.83 KB

README.md

File metadata and controls

94 lines (55 loc) · 3.83 KB
Raw

#waitForImages#

Copyright (c) 2011-2013 Alex Dickson @alexdickson

Licensed under the MIT licenses.

http://alexanderdickson.com

Donate

Build Status

##Overview##

Provides useful callbacks once descendant images have loaded.

waitForImages also supports images referenced in CSS, such as the background-image property.

It can be useful when WebKit incorrectly reports element dimensions/offsets on document ready, because it has not calculated their descendant img dimensions yet.

##Get it##

You can either grab the source yourself...

...or you can use a hosted version...

Of course, these need to be loaded after jQuery is made available. The current version supports >= jQuery 1.8. If you find incompatibility issues, please check out a previous tagged version.

##Usage##

###Standard###

Just provide a callback function and it will be called once all descendant images have loaded.

$('selector').waitForImages(function() {
	// All descendant images have loaded, now slide up.
    $(this).slideUp();	
});

this is a reference to the collection that waitForImages() was called on.

###Advanced###

You can pass a second function as a callback that will be called for each image that is loaded, with some information passed as arguments.

$('selector').waitForImages(function() {
    alert('All images have loaded.');
}, function(loaded, count, success) {
   alert(loaded + ' of ' + count + ' images has ' + (success ? 'loaded' : 'failed to load') +  '.');
   $(this).addClass('loaded');
});

You can also set the third argument to true if you'd like the plugin to iterate over the collection and all descendent elements, checking for images referenced in the CSS (by default, it looks at the background-image, list-style-image, border-image and border-corner-image properties). If it finds any, they will be treated as a descendant image.

The callback will be called on the successful and unsuccessful loading of the image. Check the third argument to determine the success of the image load. It will be true if the image loaded successfully.

If you want to skip the first argument, pass $.noop or alternatively, pass an object literal to the plugin, instead of the arguments individually.

$('selector').waitForImages({
    finished: function() {
        // ...
    },
    each: function() {
       // ...
    },
    waitForAll: true
});

You may also set the CSS properties that possibly contain image references yourself. Just assign an array of properties to the plugin.

$.waitForImages.hasImgProperties = ['backgroundImage'];

waitForImages also exposes a custom selector, :uncached, which when used in conjunction with the img selector, allows you to select img elements that are not cached already by the browser.

$('img:uncached').attr('title', 'Loading Image');

##Thanks##

##Feedback##

Please use the Issues for any bugs, feature requests, etc.