API Documentation for: 0.4.1
Show:

SamplePlugin Class

Defined in: SamplePlugin:5
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 happens in Flash

Methods

fileLoadHandler

(
  • event
)

Defined in fileLoadHandler:175

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

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

(
  • src
  • type
  • id
  • data
  • basePath
  • queue
)
Boolean | Object

Defined in preloadHandler:89

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. The arguments provided match most of those specified in load items passed into loadFile:

  • src: The item source
  • type: The item type
  • id: The item id
  • data: Arbitrary data attached to the item
  • Two additional arguments are appended:
    • basePath: A path that is prepended to all items loaded with PreloadJS. Note that basePath is deprecated, but is left in for backwards compatibility
    • queue: The LoadQueue instance that is loading the item.

    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.

    An object can also be returned which has properties that can override the existing load object. The return object can include modified src and id parameters, as well as "tag" and "completeHandler" properties:

    • tag: a JavaScript object that will handle the actual loading of the file. This is modeled after HTML image & audio tags, and must contain a load() method or a src setter, as well as and onload and onerror callback.
    • completeHandler: A method to call on the plugin once the item has been loaded. This is useful to provide any necessary post-load functionality. Check out the fileLoadHandler for more information.

    Example

     //Check out the SamplePlugin source for a more complete example.
    
     // Cancel a load
     SamplePlugin.preloadHandler = function(src, type, id, data, basePath, queue) {
         if (id.indexOf("thumb") { return false; } // Don't load items like "image-thumb.png"
         return true;
     }
    
     // Specify a completeHandler
     SamplePlugin.preloadHandler = function(src, type, id, data, basePath, queue) {
         return {
             completeHandler: SamplePlugin.fileLoadHandler
         };
     }

Parameters:

  • src String

    The path to the file, as specified by the developer, without a base path.

  • type String

    The file type, which is either passed in by the developer, or determined based on the extension. Supported load types are "binary","image", "javascript", "json", "jsonp", "sound", "svg", "text", and "xml". This value may be null if the extension is not recognized by PreloadJS.

  • id String

    The string-based ID, which is optionally passed in by the user.

  • data

    Arbitrary data optionally attached to the load item by the user, which is maintained until the item is loaded and returned to the user from PreloadJS.

  • basePath String

    A base path which is supplied to PreloadJS, which is prepended to the source of any load item.

  • queue LoadQueue

    The LoadQueue instance that is preloading the item.

Returns:

Boolean | Object:

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