API Documentation for: 0.3.0
Show:

TagLoader Class

Extends AbstractLoader
Defined in: TagLoader:39
Module: PreloadJS

A preloader that loads items using a tag-based approach. HTML audio and images can use this loader to load content cross-domain without security errors, whereas anything loaded with XHR has potential issues with cross- domain requests.

Note for audio tags, TagLoader relies on the canPlayThrough event, which fires when the buffer is full enough to play the audio all the way through at the current download speed. This completely preloads most sound effects, however longer tracks like background audio will only load a portion before the event is fired. Most browsers (all excluding Chrome) will continue to preload once this is fired, so this is considered good enough for most cases.

Constructor

TagLoader

(
  • item
)

Defined in TagLoader:39

Parameters:

  • item Object

    The item to load. Please see loadFile for information on load items.

Methods

_clean

() private

Defined in _clean:249

Clean up the loader. This stops any timers and removes references to prevent errant callbacks and clean up memory.

_handleError

() private

Defined in _handleError:198

Handle an error event generated by the tag.

_handleLoad

(
  • [event]
)
private

Defined in _handleLoad:223

Handle a load (complete) event. This is called by tag callbacks, but also by readyStateChange and canPlayThrough events. Once loaded, the item is dispatched to the LoadQueue.

Parameters:

  • [event] Object optional

    A load event from a tag. This is sometimes called from other handlers without an event.

_handleReadyStateChange

() private

Handle the readyStateChange event from a tag. We sometimes need this in place of the onload event (mainly SCRIPT and LINK tags), but other cases may exist.

_handleStalled

() private

Defined in _handleStalled:188

Handle a stalled audio event. The main place we seem to get these is with HTMLAudio in Chrome when we try and playback audio that is already in a load, but not complete.

_handleTimeout

() private

Defined in _handleTimeout:177

Handle an audio timeout. Newer browsers get a callback from the tags, but older ones may require a setTimeout to handle it. The setTimeout is always running until a response is handled by the browser.

_isCanceled

() Boolean protected

Determine if the load has been canceled. This is important to ensure that method calls or asynchronous events do not cause issues after the queue has been cleaned up.

Returns:

Boolean: If the loader has been canceled.

_parseURI

(
  • path
)
Array protected

Inherited from AbstractLoader: _parseURI:307

Parse a file URI using the AbstractLoader.FILE_PATTERN RegExp pattern.

Parameters:

  • path String

    The file path to parse.

Returns:

Array: The matched file contents. Please see the AbstractLoader.FILE_PATTERN property for details on the return value. This will return null if it does not match.

_sendComplete

() protected

Dispatch a complete event (and onComplete callback). Please see the AbstractLoader.complete event for details on the event payload.

_sendError

(
  • event
)
protected

Inherited from AbstractLoader: _sendError:277

Dispatch an error event (and onError callback). Please see the AbstractLoader.error event for details on the event payload.

Parameters:

  • event Object

    The event object containing specific error properties.

_sendLoadStart

() protected

Dispatch a loadStart event (and onLoadStart callback). Please see the AbstractLoader.loadStart event for details on the event payload.

_sendProgress

(
  • value
)
protected

Dispatch a progress event (and onProgress callback). Please see the AbstractLoader.progress event for details on the event payload.

Parameters:

  • value Number | Object

    The progress of the loaded item, or an object containing loaded and total properties.

addEventListener

(
  • type
  • listener
)
Function | Object

Adds the specified event listener.

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    An object with a handleEvent method, or a function that will be called when the event is dispatched.

Returns:

Function | Object: Returns the listener for chaining or assignment.

close

()

Inherited from AbstractLoader: close:217

Close the active queue. Closing a queue completely empties the queue, and prevents any remaining items from starting to download. Note that currently any active loads will remain open, and events may be processed.

To stop and restart a queue, use the setPaused method instead.

dispatchEvent

(
  • eventObj
  • [target]
)
Boolean

Dispatches the specified event.

Parameters:

  • eventObj Object | String

    An object with a "type" property, or a string type. If a string is used, dispatchEvent will contstruct a generic event object with "type" and "params" properties.

  • [target] Object optional

    The object to use as the target property of the event object. This will default to the dispatching object.

Returns:

Boolean: Returns true if any listener returned true.

getResult

() HTMLImageElement | HTMLAudioElement

Defined in getResult:106

Get the loaded content. This is usually an HTML tag or other tag-style object that has been fully loaded. If the loader is not complete, this will be null.

Returns:

HTMLImageElement | HTMLAudioElement: The loaded and parsed content.

hasEventListener

(
  • type
)
Boolean

Indicates whether there is at least one listener for the specified event type.

Parameters:

  • type String

    The string type of the event.

Returns:

Boolean: Returns true if there is at least one listener for the specified event.

initialize

() private

Inherited from EventDispatcher but overwritten in initialize:198

Initialize the loader. This is called by the constructor.

load

()

Inherited from AbstractLoader: load:205

Begin loading the queued items. This method can be called when a LoadQueue is set up but not started immediately.

Example:

 var queue = new createjs.LoadQueue();
 queue.addEventListener("complete", handleComplete);
 queue.loadManifest(fileArray, false); // Note the 2nd argument that tells the queue not to start loading yet
 queue.load();

removeAllEventListeners

(
  • [type]
)

Removes all listeners for the specified type, or all listeners of all types.

Parameters:

  • [type] String optional

    The string type of the event. If omitted, all listeners for all types will be removed.

removeEventListener

(
  • type
  • listener
)

Removes the specified event listener.

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    The listener function or object.

toString

() String

Inherited from EventDispatcher but overwritten in toString:320

Returns:

String: a string representation of the instance.

Properties

_isAudio

Boolean

Defined in _isAudio:80

Determines if the load item is an audio tag, since we take some specific approaches to properly load audio.

Default: false

_item

Object private

Inherited from AbstractLoader: _item:90

The item this loader represents. Note that this is null in a LoadQueue, but will be available on loaders such as XHRLoader and TagLoader.

_listeners

Object protected

Inherited from EventDispatcher: _listeners:90

_loadTimeout

Number private

Defined in _loadTimeout:62

The timeout that is fired if nothing is loaded after a certain delay. See the LoadQueue.LOAD_TIMEOUT for the timeout duration.

_tag

HTMLAudioElement | Object private

Defined in _tag:88

The HTML tag or JavaScript object this loader uses to preload content. Note that a tag may be a custom object that matches the API of an HTML tag (load method, onload callback). For example, flash audio from SoundJS passes in a custom object to handle preloading for Flash audio and WebAudio.

_tagCompleteProxy

Function private

A reference to a bound function, which we need in order to properly remove the event handler when the load completes.

canceled

Boolean

Inherited from AbstractLoader: canceled:72

Determine if the loader was canceled. Canceled loads will not fire complete events. Note that LoadQueue queues should be closed using close instead of canceled.

Default: false

loaded

Boolean

Inherited from AbstractLoader: loaded:63

If the loader has completed loading. This provides a quick check, but also ensures that the different approaches used for loading do not pile up resulting in more than one complete event.

Default: false

onComplete

Function deprecated

Inherited from AbstractLoader: onComplete:159

Deprecated: In favour of the "complete" event. Will be removed in a future version.

The callback that is fired when the loader's content has been entirely loaded.

onError

Function deprecated

Inherited from AbstractLoader: onError:167

Deprecated: In favour of the "error" event. Will be removed in a future version.

The callback that is fired when the loader encounters an error.

onLoadStart

Function deprecated

Inherited from AbstractLoader: onLoadStart:151

Deprecated: In favour of the "loadStart" event. Will be removed in a future version.

The callback that is fired when a load starts.

onProgress

Function deprecated

Inherited from AbstractLoader: onProgress:143

Deprecated: In favour of the "progress" event. Will be removed in a future version.

The callback that is fired when the overall progress changes.

progress

Number

Inherited from AbstractLoader: progress:82

The current load progress (percentage) for this item. This will be a number between 0 and 1.

Default: 0

Events

complete

Inherited from AbstractLoader: complete:120

Available since 0.3.0

The event that is fired when the entire queue has been loaded.

Event Payload:

  • target Object

    The object that dispatched the event.

  • type String

    The event type.

error

Inherited from AbstractLoader: error:128

Available since 0.3.0

The event that is fired when the loader encounters an error. If the error was encountered by a file, the event will contain the item that caused the error. There may be additional properties such as the error reason on event objects.

Event Payload:

  • target Object

    The object that dispatched the event.

  • type String

    The event type.

  • [item] Object optional

    The item that was being loaded that caused the error. The item was specified in the loadFile or loadManifest call. If only a string path or tag was specified, the object will contain that value as a property.

  • [error] String optional

    The error object or text.

loadStart

Inherited from AbstractLoader: loadStart:112

Available since 0.3.0

The event that is fired when a load starts.

Event Payload:

  • target Object

    The object that dispatched the event.

  • type String

    The event type.

progress

Inherited from AbstractLoader: progress:100

Available since 0.3.0

The event that is fired when the overall progress changes.

Event Payload:

  • target Object

    The object that dispatched the event.

  • type String

    The event type.

  • loaded Number

    The amount that has been loaded so far. Note that this is may just be a percentage of 1, since file sizes can not be determined before a load is kicked off, if at all.

  • total Number

    The total number of bytes. Note that this may just be 1.

  • percent Number

    The percentage that has been loaded. This will be a number between 0 and 1.