Things Loaded
-- Detect when images have been loaded or preload them.
Synopsis
--------
The goal of this library is to provide methods arround loading of images,
assets, media, fonts and other things (i.e. embedded video). This includes
methods to detect when a file has been loaded and methods to preload them.
As a starting point it currently support images only.
Contributions to extend the library are welcome!
The image load detection is based upon the original ImagesLoaded script. It has
been refactored and stripped down. With jQuery being the only requirement now.
Including the Library
---------------------
<script src="/path/to/jquery.js"></script>
<script src="/path/to/thingsLoaded.js"></script>
Including the Library with RequireJS
------------------------------------
require.config({
paths: {
'thingsLoaded': 'path/to/thingsLoaded',
},
shim: {
'thingsLoaded': {
deps: ['jquery'],
exports: 'ThingsLoaded'
}
}
});
Detect when Images have been loaded
-----------------------------------
var checker = new ThingsLoaded.ImageChecker();
// You can pass the addFromElement method a DOM element or
// a jQuery selector that is searched for image children.
checker.addFromElement('.post');
// Single image elements can be added like this.
$('.post').find('img').each(function(k, v) {
checker.addElement(v);
});
// URL paths can be used for checking, too.
checker.addUrl('/img/cat.png');
// The checker will also find any background images that
// are set on the element.
checker.addElement('.slide-with-background');
// The run method will return a jQuery deferred which you
// can evaluate as follows.
var check = checker.run();
check.always(function() {
// All images have been either loaded or confirmed broken.
});
check.done(function() {
// All images have successfully loaded without any broken images.
});
check.fail(function() {
// All images have been loaded with at least one broken image.
});
check.progress(function(ev, image) {
// An image has been loaded or found broken.
var result = image.isLoaded ? 'loaded' : 'broken';
});
Preload Images
--------------
var preloader = new ThingsLoaded.ImagePreloader();
preloader.addUrl('/img/logo_hover.png');
preloader.addUrl('/img/checkbox_hover.png');
// Returns a jQuery deferred similiar to the one returned by the
// checker's run method. It resolves when all images have been
// preloaded.
var preload = preloader.run();
preload.always(function() {
// All images have been preloaded.
});
Copyright & License
-------------------
ThingsLoaded is Copyright (c) 2013 David Persson if not otherwise stated. The
code is distributed under the terms of the BSD 3-clause License. For the
full license text see the LICENSE file.
The ImageChecker in ThingsLoaded was based on original code by David DeSandro.
Thus where indicated portions of that code are Copyright (c) 2013 David DeSandro
and distributed under the MIT license. For the full license text see the
LICENSE file.
Versions & Requirements
-----------------------
ThingsLoaded follows the rolling release development model. Code in the master
branch should always considered to be stable. While code in the dev branch
should be considered unstable or sometimes even expiremental.
There are no versions as in the standard release development model but
snapshots. The master branch may be tagged ("snapshotted") at any point in
time when a significant point of development has been reached.
Snapshots are schemed as follows:
[current year, four digit].[index, zero based]
jQuery is required to run the code.