API Documentation for: 1.0.0
Show:

XHRRequest Class

Extends AbstractLoader
Defined in: XHRRequest:41
Module: PreloadJS

A preloader that loads items using XHR requests, usually XMLHttpRequest. However XDomainRequests will be used for cross-domain requests if possible, and older versions of IE fall back on to ActiveX objects when necessary. XHR requests load the content as text or binary data, provide progress and consistent completion events, and can be canceled during load. Note that XHR is not supported in IE 6 or earlier, and is not recommended for cross-domain loading.

Constructor

XHRRequest

(
  • item
)

Defined in XHRRequest:41

Parameters:

  • item Object

    The object that defines the file to load. Please see the loadFile for an overview of supported file properties.

Methods

_checkError

() Error private

Defined in _checkError:384

Determine if there is an error in the current load. Currently this checks the status of the request for problem codes, and not actual response content:

  • Status codes between 400 and 599 (HTTP error range)
  • A status of 0, but only when the application is running on a server. If the application is running on file:, then it may incorrectly treat an error on local (or embedded applications) as a successful load.

Returns:

Error:

An error with the status code in the message argument.

_clean

() private

Defined in _clean:539

A request has completed (or failed or canceled), and needs to be disposed.

_createRequest

() protected

Create an internal request used for loading. By default, an XHRRequest or TagRequest is created, depending on the value of PreferXHR:property. Other loaders may override this to use different request types, such as ManifestLoader, which uses JSONLoader or JSONPLoader under the hood.

_createTag

(
  • src
)
HTMLElement protected

Inherited from AbstractLoader: _createTag:425

Create the HTML tag used for loading. This method does nothing by default, and needs to be implemented by loaders that require tag loading.

Parameters:

Returns:

HTMLElement:

The tag that was created

_createXHR

(
  • item
)
Boolean private

Defined in _createXHR:444

Create an XHR request. Depending on a number of factors, we get totally different results.

  1. Some browsers get an XDomainRequest when loading cross-domain.
  2. XMLHttpRequest are created when available.
  3. ActiveX.XMLHTTP objects are used in older IE browsers.
  4. Text requests override the mime type if possible
  5. Origin headers are sent for crossdomain requests in some browsers.
  6. Binary loads set the response type to "arraybuffer"

Parameters:

  • item Object

    The requested item that is being loaded.

Returns:

Boolean:

If an XHR request or equivalent was successfully created.

_dispatchEvent

(
  • eventObj
  • eventPhase
)
protected

Parameters:

_getResponse

() private

Defined in _getResponse:410

Validate the response. Different browsers have different approaches, some of which throw errors when accessed in other browsers. If there is no response, the _response property will remain null.

_handleError

(
  • event
)
private

Defined in _handleError:304

The XHR request has reported an error event.

Parameters:

  • event Object

    The XHR error event.

_handleLoad

(
  • event
)
private

Defined in _handleLoad:328

The XHR request has completed. This is called by the XHR request directly, or by a readyStateChange that has request.readyState == 4. Only the first call to this method will be processed.

Note that This method uses _checkError to determine if the server has returned an error code.

Parameters:

  • event Object

    The XHR load event.

_handleLoadStart

(
  • event
)
private

The XHR request has reported a load start.

Parameters:

  • event Object

    The XHR loadStart event.

_handleProgress

(
  • event
)
private

Defined in _handleProgress:267

The XHR request has reported progress.

Parameters:

  • event Object

    The XHR progress event.

_handleReadyStateChange

(
  • event
)
private

The XHR request has reported a readyState change. Note that older browsers (IE 7 & 8) do not provide an onload event, so we must monitor the readyStateChange to determine if the file is loaded.

Parameters:

  • event Object

    The XHR readyStateChange event.

_handleTimeout

(
  • [event]
)
private

Defined in _handleTimeout:371

The XHR request has timed out. This is called by the XHR request directly, or via a setTimeout callback.

Parameters:

  • [event] Object optional

    The XHR timeout event. This is occasionally null when called by the backup setTimeout.

_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.

_resultFormatSuccess

(
  • result
)
private

Inherited from AbstractLoader but overwritten in _resultFormatSuccess:568

The "success" callback passed to AbstractLoader/resultFormatter asynchronous functions.

Parameters:

  • result Object

    The formatted result

_sendComplete

() protected

Dispatch a complete Event. Please see the complete event

_sendError

(
  • event
)
protected

Inherited from AbstractLoader: _sendError:488

Dispatch an error Event. Please see the error event for details on the event payload.

Parameters:

  • event ErrorEvent

    The event object containing specific error properties.

_sendLoadStart

() protected

Dispatch a loadstart Event. Please see the loadstart event for details on the event payload.

_sendProgress

(
  • value
)
protected

Dispatch a ProgressEvent.

Parameters:

  • value Number | Object

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

addEventListener

(
  • type
  • listener
  • [useCapture]
)
Function | Object

Adds the specified event listener. Note that adding multiple listeners to the same function will result in multiple callbacks getting fired.

Example

 displayObject.addEventListener("click", handleClick);
 function handleClick(event) {
    // Click happened.
 }

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.

  • [useCapture] Boolean optional

    For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

Returns:

Function | Object:

Returns the listener for chaining or assignment.

cancel

()

Inherited from AbstractLoader: cancel:365

Close the the item. This will stop any open requests (although downloads using HTML tags may still continue in the background), but events will not longer be dispatched.

destroy

()

Inherited from AbstractLoader: destroy:375

Clean up the loader.

dispatchEvent

(
  • eventObj
  • [bubbles]
  • [cancelable]
)
Boolean

Dispatches the specified event to all listeners.

Example

 // Use a string event
 this.dispatchEvent("complete");

 // Use an Event instance
 var event = new createjs.Event("progress");
 this.dispatchEvent(event);

Parameters:

  • eventObj Object | String | Event

    An object with a "type" property, or a string type. While a generic object will work, it is recommended to use a CreateJS Event instance. If a string is used, dispatchEvent will construct an Event instance if necessary with the specified type. This latter approach can be used to avoid event object instantiation for non-bubbling events that may not have any listeners.

  • [bubbles] Boolean optional

    Specifies the bubbles value when a string was passed to eventObj.

  • [cancelable] Boolean optional

    Specifies the cancelable value when a string was passed to eventObj.

Returns:

Boolean:

Returns false if preventDefault() was called on a cancelable event, true otherwise.

getAllResponseHeaders

() String

Defined in getAllResponseHeaders:229

Available since 0.4.1

Get all the response headers from the XmlHttpRequest.

From the docs: Return all the HTTP headers, excluding headers that are a case-insensitive match for Set-Cookie or Set-Cookie2, as a single string, with each header line separated by a U+000D CR U+000A LF pair, excluding the status line, and with each header name and header value separated by a U+003A COLON U+0020 SPACE pair.

Returns:

getItem

() Object

Inherited from AbstractLoader: getItem:290

Available since 0.6.0

Get a reference to the manifest item that is loaded by this loader. In some cases this will be the value that was passed into LoadQueue using loadFile or loadManifest. However if only a String path was passed in, then it will be a LoadItem.

Returns:

Object:

The manifest item that this loader is responsible for loading.

getLoadedItems

() Array

Inherited from AbstractLoader: getLoadedItems:396

Available since 0.6.0

Get any items loaded internally by the loader. The enables loaders such as ManifestLoader to expose items it loads internally.

Returns:

Array:

A list of the items loaded by the loader.

getResponseHeader

(
  • header
)
String

Defined in getResponseHeader:248

Available since 0.4.1

Get a specific response header from the XmlHttpRequest.

From the docs: Returns the header field value from the response of which the field name matches header, unless the field name is Set-Cookie or Set-Cookie2.

Parameters:

  • header String

    The header name to retrieve.

Returns:

getResult

(
  • [raw=false]
)
Object

Inherited from AbstractLoader but overwritten in getResult:139

Look up the loaded result.

Parameters:

  • [raw=false] Boolean optional

    Return a raw result instead of a formatted result. This applies to content loaded via XHR such as scripts, XML, CSS, and Images. If there is no raw result, the formatted result will be returned instead.

Returns:

Object:

A result object containing the content that was loaded, such as:

  • An image tag (<image />) for images
  • A script tag for JavaScript (<script />). Note that scripts loaded with tags may be added to the HTML head.
  • A style tag for CSS (<style />)
  • Raw text for TEXT
  • A formatted JavaScript object defined by JSON
  • An XML document
  • An binary arraybuffer loaded by XHR
Note that if a raw result is requested, but not found, the result will be returned instead.

getTag

() Object

Inherited from AbstractLoader: getTag:316

Available since 0.6.0

Return the tag this object creates or uses for loading.

Returns:

Object:

The tag instance

handleAbort

(
  • event
)
private

Defined in handleAbort:293

The XHR request has reported an abort event.

Parameters:

  • event Object

    The XHR abort event.

handleEvent

(
  • event
)
protected

Inherited from AbstractLoader: handleEvent:525

Available since 0.6.0

Handle events from internal requests. By default, loaders will handle, and redispatch the necessary events, but this method can be overridden for custom behaviours.

Parameters:

  • event Event

    The event that the internal request dispatches.

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.

load

()

Inherited from AbstractLoader: load:336

Begin loading the item. This method is required when using a loader by itself.

Example

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

off

(
  • type
  • listener
  • [useCapture]
)

Inherited from EventDispatcher: off:249

A shortcut to the removeEventListener method, with the same parameters and return value. This is a companion to the .on method.

IMPORTANT: To remove a listener added with on, you must pass in the returned wrapper function as the listener. See on for an example.

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    The listener function or object.

  • [useCapture] Boolean optional

    For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

on

(
  • type
  • listener
  • [scope]
  • [once=false]
  • [data]
  • [useCapture=false]
)
Function

Inherited from EventDispatcher: on:173

A shortcut method for using addEventListener that makes it easier to specify an execution scope, have a listener only run once, associate arbitrary data with the listener, and remove the listener.

This method works by creating an anonymous wrapper function and subscribing it with addEventListener. The wrapper function is returned for use with removeEventListener (or off).

IMPORTANT: To remove a listener added with on, you must pass in the returned wrapper function as the listener, or use remove. Likewise, each time you call on a NEW wrapper function is subscribed, so multiple calls to on with the same params will create multiple listeners.

Example

    var listener = myBtn.on("click", handleClick, null, false, {count:3});
    function handleClick(evt, data) {
        data.count -= 1;
        console.log(this == myBtn); // true - scope defaults to the dispatcher
        if (data.count == 0) {
            alert("clicked 3 times!");
            myBtn.off("click", listener);
            // alternately: evt.remove();
        }
    }

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.

  • [scope] Object optional

    The scope to execute the listener in. Defaults to the dispatcher/currentTarget for function listeners, and to the listener itself for object listeners (ie. using handleEvent).

  • [once=false] Boolean optional

    If true, the listener will remove itself after the first time it is triggered.

  • [data] optional

    Arbitrary data that will be included as the second parameter when the listener is called.

  • [useCapture=false] Boolean optional

    For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

Returns:

Function:

Returns the anonymous function that was created and assigned as the listener. This is needed to remove the listener later using .removeEventListener.

removeAllEventListeners

(
  • [type]
)

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

Example

 // Remove all listeners
 displayObject.removeAllEventListeners();

 // Remove all click listeners
 displayObject.removeAllEventListeners("click");

Parameters:

  • [type] String optional

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

removeEventListener

(
  • type
  • listener
  • [useCapture]
)

Removes the specified event listener.

Important Note: that you must pass the exact function reference used when the event was added. If a proxy function, or function closure is used as the callback, the proxy/closure reference must be used - a new proxy or closure will not work.

Example

 displayObject.removeEventListener("click", handleClick);

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    The listener function or object.

  • [useCapture] Boolean optional

    For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

setTag

(
  • tag
)

Inherited from AbstractLoader: setTag:326

Available since 0.6.0

Set the tag this item uses for loading.

Parameters:

toString

() String

Inherited from EventDispatcher but overwritten in toString:591

Returns:

String:

a string representation of the instance.

willTrigger

(
  • type
)
Boolean

Indicates whether there is at least one listener for the specified event type on this object or any of its ancestors (parent, parent's parent, etc). A return value of true indicates that if a bubbling event of the specified type is dispatched from this object, it will trigger at least one listener.

This is similar to hasEventListener, but it searches the entire event flow for a listener, not just this object.

Parameters:

  • type String

    The string type of the event.

Returns:

Boolean:

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

Properties

_captureListeners

Object protected

_item

LoadItem | Object private

Inherited from AbstractLoader: _item:127

The LoadItem this loader represents. Note that this is null in a LoadQueue, but will be available on loaders such as XMLLoader and ImageLoader.

_listeners

Object protected

Inherited from EventDispatcher: _listeners:99

_loadItems

Null protected

Inherited from AbstractLoader: _loadItems:167

A list of items that loaders load behind the scenes. This does not include the main item the loader is responsible for loading. Examples of loaders that have sub-items include the SpriteSheetLoader and ManifestLoader.

_loadTimeout

Number private

Defined in _loadTimeout:65

A manual load timeout that is used for browsers that do not support the onTimeout event on XHR (XHR level 1, typically IE9).

_preferXHR

Boolean private

Inherited from AbstractLoader: _preferXHR:140

Whether the loader will try and load content using XHR (true) or HTML tags (false).

_rawResponse

String | Object private

Defined in _rawResponse:93

The response of the loaded file before it is modified. In most cases, content is converted from raw text to an HTML tag or a formatted object which is set to the result property, but the developer may still want to access the raw content as it was loaded.

_rawResult

Object | String private

Inherited from AbstractLoader: _rawResult:158

The loaded result before it is formatted. The rawResult is accessed using the GetResult method, and passing true.

_request

XMLHttpRequest | XDomainRequest | ActiveX.XMLHTTP private

Defined in _request:57

A reference to the XHR request used to load the content.

_response

Mixed private

Defined in _response:84

The response of a loaded file. This is set because it is expensive to look up constantly. This property will be null until the file is loaded.

_result

Object | String private

Inherited from AbstractLoader: _result:148

The loaded result after it is formatted by an optional ResultFormatter. For items that are not formatted, this will be the same as the _rawResult:property. The result is accessed using the GetResult method.

_tag

Object private

Inherited from AbstractLoader: _tag:185

An HTML tag (or similar) that a loader may use to load HTML content, such as images, scripts, etc.

_xhrLevel

Number private

Defined in _xhrLevel:74

The browser's XHR (XMLHTTPRequest) version. Supported versions are 1 and 2. There is no official way to detect the version, so we use capabilities to make a best guess.

Default: 1

ACTIVEX_VERSIONS

Array private

Defined in ACTIVEX_VERSIONS:122

Available since 0.4.2

A list of XMLHTTP object IDs to try when building an ActiveX object for XHR requests in earlier versions of IE.

canceled

Boolean readonly

Inherited from AbstractLoader: canceled:66

Determine if the loader was canceled. Canceled loads will not fire complete events. Note that this property is readonly, so LoadQueue queues should be closed using close instead.

Default: false

loaded

Boolean

Inherited from AbstractLoader: loaded:57

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

progress

Number

Inherited from AbstractLoader: progress:77

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

Example

var queue = new createjs.LoadQueue();
queue.loadFile("largeImage.png");
queue.on("progress", function() {
    console.log("Progress:", queue.progress, event.progress);
});

Default: 0

resultFormatter

Function

Inherited from AbstractLoader but overwritten in resultFormatter:102

A formatter function that converts the loaded raw result into the final result. For example, the JSONLoader converts a string of text into a JavaScript object. Not all loaders have a resultFormatter, and this property can be overridden to provide custom formatting.

Optionally, a resultFormatter can return a callback function in cases where the formatting needs to be asynchronous, such as creating a new image. The callback function is passed 2 parameters, which are callbacks to handle success and error conditions in the resultFormatter. Note that the resultFormatter method is called in the current scope, as well as the success and error callbacks.

Example asynchronous resultFormatter

function _formatResult(loader) {
    return function(success, error) {
        if (errorCondition) { error(errorDetailEvent); }
        success(result);
    }
}

Default: null

type

String

Inherited from AbstractLoader: type:94

The type of item this loader will load. See AbstractLoader for a full list of supported types.

Events

complete

Inherited from AbstractLoader: complete:237

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:245

Available since 0.3.0

The ErrorEvent 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. Prior to version 0.6.0, this was just a regular Event.

fileerror

Inherited from AbstractLoader: fileerror:253

Available since 0.6.0

The Event that is fired when the loader encounters an internal file load error. This enables loaders to maintain internal queues, and surface file load errors.

Event Payload:

  • target Object

    The object that dispatched the event.

  • type String

    The event type ("fileerror")

  • The LoadItem | Object

    item that encountered the error

fileload

Inherited from AbstractLoader: fileload:263

Available since 0.6.0

The Event that is fired when a loader internally loads a file. This enables loaders such as ManifestLoader to maintain internal LoadQueues and notify when they have loaded a file. The LoadQueue class dispatches a slightly different fileload event.

Event Payload:

  • target Object

    The object that dispatched the event.

  • type String

    The event type ("fileload")

  • item Object

    The file item which 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 src property.

  • result Object

    The HTML tag or parsed result of the loaded item.

  • rawResult Object

    The unprocessed result, usually the raw text or binary data before it is converted to a usable object.

initialize

Inherited from AbstractLoader: initialize:280

The Event that is fired after the internal request is created, but before a load. This allows updates to the loader for specific loading needs, such as binary or XHR image loading.

Event Payload:

  • target Object

    The object that dispatched the event.

  • type String

    The event type ("initialize")

  • loader AbstractLoader

    The loader that has been initialized.

loadstart

Inherited from AbstractLoader: loadstart:229

Available since 0.3.1

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:222

Available since 0.3.0

The ProgressEvent that is fired when the overall progress changes. Prior to version 0.6.0, this was just a regular Event.