API Documentation for: 0.6.0
Show:

SamplePlugin Class

Defined in: SamplePlugin:8
Module: PreloadJS

A PreloadJS plugin provides a way to inject functionality into PreloadJS to load file types that are unsupported, or in a way that PreloadJS does not.

Note that this class is mainly for documentation purposes, and is not a real plugin.

Plugins are registered based on file extension, or supported preload types, which are defined as constants on the LoadQueue class. Available load types are:

A plugin defines what types or extensions it handles via a getPreloadHandlers method, which is called when a plugin is first registered.

To register a plugin with PreloadJS, simply install it into a LoadQueue before files begin to load using the installPlugin method:

 var queue = new createjs.LoadQueue();
 queue.installPlugin(createjs.SamplePlugin);
 queue.loadFile("test.jpg");

The getPreloadHandlers method can also return a callback property, which is a function that will be invoked before each file is loaded. Check out the preloadHandler for more information on how the callback works. For example, the SoundJS plugin allows PreloadJS to manage a download that uses the Flash Player.

Methods

fileLoadHandler

(
  • event
)

Defined in fileLoadHandler:156

This is a sample method to show a completeHandler, which is optionally specified by the return object in the preloadHandler. This sample provides a completeHandler to the LoadItem. This method is called after the item has completely loaded, but before the fileload event is dispatched from the LoadQueue.

The provided sample also listens for the complete event on the loader it returns to show a different usage.

Parameters:

getPreloadHandlers

() Object

When a plugin is installed, this method will be called to let PreloadJS know when to invoke the plugin.

PreloadJS expects this method to return an object containing:

  • callback: The function to call on the plugin class right before an item is loaded. Check out the preloadHandler method for more information. The callback is automatically called in the scope of the plugin.
  • types: An array of recognized PreloadJS load types to handle. Supported load types are "binary","image", "javascript", "json", "jsonp", "sound", "svg", "text", and "xml".
  • extensions: An array of strings containing file extensions to handle, such as "jpg", "mp3", etc. This only fires if an applicable type handler is not found by the plugin.

Note that currently, PreloadJS only supports a single handler for each extension or file type.

Example

 // Check out the SamplePlugin source for a more complete example.
 SamplePlugin.getPreloadHandlers = function() {
     return {
         callback: SamplePlugin.preloadHandler,
         extensions: ["jpg", "jpeg", "png", "gif"]
     }
 }

If a plugin provides both "type" and "extension" handlers, the type handler will take priority, and will only fire once per file. For example if you have a handler for type=sound, and for extension=mp3, the callback will fire when it matches the type.

Returns:

Object:

An object defining a callback, type handlers, and extension handlers (see description)

preloadHandler

(
  • loadItem
  • queue
)
Boolean | AbstractLoader

Defined in preloadHandler:94

This is a sample method to show how to handle the callback specified in the LoadQueue/getPreloadHandlers. Right before a file is loaded, if a plugin for the file type or extension is found, then the callback for that plugin will be invoked. This gives the plugin an opportunity to modify the load item, or even cancel the load. The return value of the callback determines how PreloadJS will handle the file:

  • false: Skip the item. This allows plugins to determine if a file should be loaded or not. For example,the plugin could determine if a file type is supported at all on the current system, and skip those that do not.
  • true: Continue normally. The plugin will not affect the load.
  • AbstractLoader instance: Used as the loader for the content. This is new in 0.6.0.

Since the LoadItem is passed by reference, a plugin can modify as needed, even appending additional data to it. Note that if the src is modified, PreloadJS will automatically update the LoadItem/ext:property property.

Example

 // Cancel a load
 SamplePlugin.preloadHandler = function(loadItem, queue) {
     if (loadItem.id.indexOf("thumb") { return false; } // Don't load items like "image-thumb.png"
     return true;
 }

 // Specify a completeHandler
 SamplePlugin.preloadHandler = function(loadItem, queue) {
     item.completeHandler = SamplePlugin.fileLoadHandler;
 }

 // Check out the SamplePlugin source to see another example.

Note: In 0.4.2 and earlier, instead of a LoadItem, arguments were passed in, and a modified object was returned to PreloadJS. This has been changed to passing a reference to the LoadItem, which can be directly modified.

Parameters:

  • loadItem LoadItem | Object

    The item that PreloadJS is going to load. This item is passes by reference, so it can be directly modified.

  • queue LoadQueue

    The LoadQueue instance that is preloading the item.

Returns:

Boolean | AbstractLoader:

How PreloadJS should handle the load. See the main description for more info.