Loads and Preloads
JavaScript
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
README.md
ResourceLoader.js

README.md

ResourceLoader


Updates:

9/11/12:

  • Callback function now receives an array of loaded resources as an argument
  • Added source attribute

8/22/12:

  • Uploaded Alpha Release

Dependencies:

None


Usage:

The ResourceLoader object only has two functions: load() and get(). Simple right?

Currently, it can only be used to load image and sound files.

The load() function takes any number of arguments: the first argument is an optional callback function that will be invoked once each resource loads (or fails to load), and any additional arguments specify the resources to load.

If the load() function tries to load resources that have already loaded, the callback function will be called instantly. This, in combination with callback-free load() calls, allow for resource preloading.

Example:


function callback() {console.log("Success!")}
function someOtherCallback() {console.log("Woot!")}

//Load and image and a sound and invoke a callback once finished
ResourceLoader.load(callback, "image.jpg", "sound.mp3");

//Load some images, but don't invoke a callback
ResourceLoader.load("image2.jpg", "image3.jpg", "image4.png");

//Another acceptable way to not issue a callback
ResourceLoader.load(null, "music.ogg");

// .. some time later ..

//"music.ogg" has already loaded (or started to),
//so 'someOtherCallback()' gets invoked much sooner.
ResourceLoader.load(someOtherCallback, "music.ogg");


The function specified as the callback will also receive an argument referencing all the resources that successfully loaded (by name):


function callback(resources) {
	for(var i = 0; i < resources.length; i++) {
		console.log("This resource loaded: " + resources[i]);
	}
}

ResourceLoader.load(callback, "img1.jpg", "img2.jpg", "sound.wav");


The get() function attempts to return a loaded resource, but will return null if the resource hasn't loaded. For this reason, it should only be called from within a callback function invoked by the load() function.

The get() function can also return null if a resource failed to load. This is common with audio format inconsistencies across browsers, but can also happen if a resource simply isn't found, or if it has a bizarre extension. Whenever you're unsure about a resource's ability to load, you should make sure that the result of the get() function isn't null.

Example:


function someFunction() {
	console.log("Width: " + ResourceLoader.get("img.gif").width);
}

ResourceLoader.load(someFunction, "img.gif");

Audio resources are a special case. To circumvent the unsupported audio format problems apparent in all modern browsers, the get() function will return any working audio object it can find, granted it has the same path and name minus the extension.

Consider the following code:


function callback() {
	//This will play the .wav file if .mp3 doesn't work
	ResourceLoader.get("sounds/sound.mp3").play();
}

ResourceLoader.load(callback, "sounds/sound.mp3", "sounds/sound.wav");

Since Firefox doesn't like .mp3 files, the get() function will look for another resource that has the same name, in this case, "sound.wav", and use that instead. Of course, if a suitable audio resource isn't found, the get() function will return null, so make sure to check for that if you can't use backup formats.

Elements returned by the get() function will have a .source attribute, which references the user-specified path of the file. This attribute is important because element's .src attributes becomes an absolute paths when they are loaded, and because retrieving an audio tag with get() won't necessarily reference the audio tag with the same extension.

Ex:


function callback() {
	
	//Displays "image.jpg" as opposed to "www.somewebsite.com/files/images/image.jpg"
	console.log(ResourceLoader.get("image.jpg").source);
	
	//On firefox, this will display "sound.wav"
	console.log(ResourceLoader.get("sound.mp3").source);
}

ResourceLoader.load(callback, "image.jpg", "sound.mp3", "sound.wav");


Browser Support:

All latest versions of Safari, Firefox, Opera, and Chrome seem to behave normally. It probably doesn't work in IE because, well, IE sucks. I have yet to test it in any version Explorer, but you're free to do so ;)


Bugs:

  • Sounds can play prematurely for a brief period after loading.

  • Probably doesn't work in Internet Explorer


About:

ResourceLoader is a refined portion of an old GameAPI I made nearly a year ago. It's been separated so that it can be maintained more easily, and also to allow other developers to use it for other things.