Show:
Module: io-base
Parent Module: io

The IO class is a utility that brokers HTTP requests through a simplified interface. Specifically, it allows JavaScript to make HTTP requests to a resource without a page reload. The underlying transport for making same-domain requests is the XMLHttpRequest object. IO can also use Flash, if specified as a transport, for cross-domain requests.

Constructor

IO

(
  • config
)

Parameters:

  • config Object

    Object of EventTarget's publish method configurations used to configure IO's events.

    IO can be called statically using YUI.io.

Methods

_abort

(
  • o
  • c
)
private

Provided by the io-xdr module.

Defined in yui3/src/io/js/io-xdr.js:92

Method for intiating an XDR transaction abort.

Parameters:

  • o Object
    • Transaction object generated by _create() in io-base.
  • c Object
    • configuration object for the transaction.

_abort

(
  • transaction
  • type
)
private

Terminates a transaction due to an explicit abort or timeout.

Parameters:

  • transaction Object

    Transaction object generated by _create().

  • type String

    Identifies timed out or aborted transaction.

_addData

(
  • f
  • s
)
Array private static

Provided by the io-upload-iframe module.

Defined in yui3/src/io/js/io-upload-iframe.js:50

Parses the POST data object and creates hidden form elements for each key-value, and appends them to the HTML form object.

Parameters:

  • f Object

    HTML form object.

  • s String

    The key-value POST data.

Returns:

Array:

o Array of created fields.

_cFrame

(
  • o
  • c
  • io
)
private

Provided by the io-upload-iframe module.

Defined in yui3/src/io/js/io-upload-iframe.js:15

Creates the iframe transported used in file upload transactions, and binds the response event handler.

Parameters:

  • o Object

    Transaction object generated by _create().

  • c Object

    Configuration object passed to YUI.io().

  • io Object

_clearTimeout

(
  • id
)
private

Clears the timeout interval started by _startTimeout().

Parameters:

_clearUploadTimeout

(
  • id
)
private static

Provided by the io-upload-iframe module.

Defined in yui3/src/io/js/io-upload-iframe.js:170

Clears the timeout interval started by _startUploadTimeout().

Parameters:

_concat

(
  • uri
  • data
)
String private

Method that concatenates string data for HTTP GET transactions.

Parameters:

  • uri String

    URI or root data.

  • data String

    Data to be concatenated onto URI.

Returns:

String:

_create

(
  • cfg
  • id
)
Object private

Method that creates a unique transaction object for each request.

Parameters:

  • cfg Object

    Configuration object subset to determine if the transaction is an XDR or file upload, requiring an alternate transport.

  • id Number

    Transaction id

Returns:

Object:

The transaction object

_data

(
  • o
  • u
  • d
)
Object private

Provided by the io-xdr module.

Defined in yui3/src/io/js/io-xdr.js:69

Creates a response object for XDR transactions, for success and failure cases.

Parameters:

  • o Object
    • Transaction object generated by _create() in io-base.
  • u Boolean
    • Configuration xdr.use.
  • d Boolean
    • Configuration xdr.dataType.

Returns:

Object:

_dFrame

(
  • id
)
private

Provided by the io-upload-iframe module.

Defined in yui3/src/io/js/io-upload-iframe.js:35

Removes the iframe transport used in the file upload transaction.

Parameters:

  • id Number

    The transaction ID used in the iframe's creation.

_evt

(
  • eventName
  • transaction
  • config
)
private

Method for creating and firing events.

Parameters:

  • eventName String

    Event to be published.

  • transaction Object

    Transaction object.

  • config Object

    Configuration data subset for event subscription.

_ieEvt

(
  • o
  • c
)
private static

Provided by the io-xdr module.

Defined in yui3/src/io/js/io-xdr.js:127

Sets event handlers for XDomainRequest transactions.

Parameters:

  • o Object
    • Transaction object generated by _create() in io-base.
  • c Object
    • configuration object for the transaction.

_isInProgress

(
  • o
)
private

Provided by the io-xdr module.

Defined in yui3/src/io/js/io-xdr.js:104

Method for determining if an XDR transaction has completed and all data are received.

Parameters:

  • o Object
    • Transaction object generated by _create() in io-base.

_qShift

() private static

Provided by the io-queue module.

Defined in yui3/src/io/js/io-queue.js:35

Method Process the first transaction from the queue in FIFO order.

_removeData

(
  • f
  • o
)
private static

Provided by the io-upload-iframe module.

Defined in yui3/src/io/js/io-upload-iframe.js:88

Removes the custom fields created to pass additional POST data, along with the HTML form fields.

Parameters:

  • f Object

    HTML form object.

  • o Object

    HTML form fields created from configuration.data.

_resetAttrs

(
  • f
  • a
)
private static

Provided by the io-upload-iframe module.

Defined in yui3/src/io/js/io-upload-iframe.js:128

Reset the HTML form attributes to their original values.

Parameters:

  • f Object

    HTML form object.

  • a Object

    Object of original attributes.

_result

(
  • transaction
  • config
)
private static

Method that determines if a transaction response qualifies as success or failure, based on the response HTTP status code, and fires the appropriate success or failure events.

Parameters:

  • transaction Object

    Transaction object generated by _create().

  • config Object

    Configuration object passed to io().

_retry

(
  • transaction
  • uri
  • config
)
private

Retry an XDR transaction, using the Flash tranport, if the native transport fails.

Parameters:

  • transaction Object

    Transaction object.

  • uri String

    Qualified path to transaction resource.

  • config Object

    Configuration object for the transaction.

_rS

(
  • transaction
  • config
)
private

Event handler bound to onreadystatechange.

Parameters:

  • transaction Object

    Transaction object generated by _create().

  • config Object

    Configuration object passed to YUI.io().

_serialize

(
  • c
  • s
)
String private

Provided by the io-form module.

Defined in yui3/src/io/js/io-form.js:36

Enumerate through an HTML form's elements collection and return a string comprised of key-value pairs.

Parameters:

  • c Object
    • id String | Element

      YUI form node or HTML form id

    • useDisabled Boolean

      true to include disabled fields

  • s String

    Key-value data defined in the configuration object.

Returns:

String:

_setAttrs

(
  • f
  • id
  • uri
)
private static

Provided by the io-upload-iframe module.

Defined in yui3/src/io/js/io-upload-iframe.js:105

Sets the appropriate attributes and values to the HTML form, in preparation of a file upload transaction.

Parameters:

  • f Object

    HTML form object.

  • id Object

    The Transaction ID.

  • uri Object

    Qualified path to transaction resource.

_setHeaders

(
  • transaction
  • headers
)
private

Method that sets all HTTP headers to be sent in a transaction.

Parameters:

  • transaction Object
    • XHR instance for the specific transaction.
  • headers Object
    • HTTP headers for the specific transaction, as defined in the configuration object passed to YUI.io().

_size

() Number private static

Provided by the io-queue module.

Defined in yui3/src/io/js/io-queue.js:144

Method to query the current size of the queue.

Returns:

_startTimeout

(
  • transaction
  • timeout
)
private

Starts timeout count if the configuration object has a defined timeout property.

Parameters:

  • transaction Object

    Transaction object generated by _create().

  • timeout Object

    Timeout in milliseconds.

_startUploadTimeout

(
  • o
  • c
)
private static

Provided by the io-upload-iframe module.

Defined in yui3/src/io/js/io-upload-iframe.js:147

Starts timeout count if the configuration object has a defined timeout property.

Parameters:

  • o Object

    Transaction object generated by _create().

  • c Object

    Configuration object passed to YUI.io().

_stop

() private static

Provided by the io-queue module.

Defined in yui3/src/io/js/io-queue.js:130

Method for setting queue processing to inactive. Transaction requests to YUI.io.queue() will be stored in the queue, but not processed until the queue is reset to "active".

_swf

(
  • uri
  • yid
  • uid
)
private

Provided by the io-xdr module.

Defined in yui3/src/io/js/io-xdr.js:47

Method that creates the Flash transport swf.

Parameters:

  • uri String
    • location of io.swf.
  • yid String
    • YUI sandbox id.
  • uid String
    • IO instance id.

_upload

(
  • o
  • uri
  • c
)
private static

Provided by the io-upload-iframe module.

Defined in yui3/src/io/js/io-upload-iframe.js:228

Uploads HTML form data, inclusive of files/attachments, using the iframe created in _create to facilitate the transaction.

Parameters:

  • o Object

    The transaction object

  • uri Object

    Qualified path to transaction resource.

  • c Object

    Configuration object for the transaction.

_uploadComplete

(
  • o
  • c
)
private static

Provided by the io-upload-iframe module.

Defined in yui3/src/io/js/io-upload-iframe.js:184

Bound to the iframe's Load event and processes the response data.

Parameters:

  • o Object

    The transaction object

  • c Object

    Configuration object for the transaction.

_xdrReady

(
  • yid
  • uid
)
private

Provided by the io-xdr module.

Defined in yui3/src/io/js/io-xdr.js:252

Fires event "io:xdrReady"

Parameters:

complete

(
  • transaction
  • config
)

Fires event "io:complete" and creates, fires a transaction-specific "complete" event, if config.on.complete is defined.

Parameters:

  • transaction Object

    Transaction object.

  • config Object

    Configuration object for the transaction.

empty

() static

Provided by the io-queue module.

Defined in yui3/src/io/js/io-queue.js:108

Available since 3.7.3

Method for cancel all pending transaction from the queue.

end

(
  • transaction
  • config
)

Fires event "io:end" and creates, fires a transaction-specific "end" event, if config.on.end is defined.

Parameters:

  • transaction Object

    Transaction object.

  • config Object

    Configuration object for the transaction.

error

(
  • transaction
  • error
  • config
)

Fires event "io:failure" and creates, fires a transaction-specific "failure" event -- for XMLHttpRequest file upload -- if config.on.failure is defined.

Parameters:

  • transaction Object

    Transaction object.

  • error Object

    event.

  • config Object

    Configuration object for the transaction.

failure

(
  • transaction
  • config
)

Fires event "io:failure" and creates, fires a transaction-specific "failure" event, if config.on.failure is defined.

Parameters:

  • transaction Object

    Transaction object.

  • config Object

    Configuration object for the transaction.

flatten

(
  • o
)
String protected

Provided by the io-nodejs module.

Defined in yui3/src/io/js/io-nodejs.js:23

Flatten headers object

Parameters:

  • o Object

    The headers object

Returns:

String:

The flattened headers object

load

(
  • transaction
  • load
  • config
)

Fires event "io:complete" and creates, fires a transaction-specific "complete" event -- for XMLHttpRequest file upload -- if config.on.complete is defined.

Parameters:

  • transaction Object

    Transaction object.

  • load Object

    event.

  • config Object

    Configuration object for the transaction.

progress

(
  • transaction
  • progress
  • config
)

Fires event "io:progress" and creates, fires a transaction-specific "progress" event -- for XMLHttpRequest file upload -- if config.on.progress is defined.

Parameters:

  • transaction Object

    Transaction object.

  • progress Object

    event.

  • config Object

    Configuration object for the transaction.

promote

() static

Provided by the io-queue module.

Defined in yui3/src/io/js/io-queue.js:86

Method for promoting a transaction to the top of the queue.

queue

() Object static

Provided by the io-queue module.

Defined in yui3/src/io/js/io-queue.js:52

Method for queueing a transaction before the request is sent to the resource, to ensure sequential processing.

Returns:

Object:

remove

() private static

Provided by the io-queue module.

Defined in yui3/src/io/js/io-queue.js:96

Method for removing a specific, pending transaction from the queue.

request

() static

Provided by the io-nodejs module.

Defined in yui3/src/io/js/io-nodejs.js:7

Passthru to the NodeJS <a href="https://github.com/mikeal/request">request</a> module. This method is return of require('request') so you can use it inside NodeJS without the IO abstraction.

send

(
  • uri
  • config
  • id
)
Object public

Requests a transaction. send() is implemented as Y.io(). Each transaction may include a configuration object. Its properties are:

<dl> <dt>method</dt> <dd>HTTP method verb (e.g., GET or POST). If this property is not not defined, the default value will be GET.</dd>

<dt>data</dt> <dd>This is the name-value string that will be sent as the transaction data. If the request is HTTP GET, the data become part of querystring. If HTTP POST, the data are sent in the message body.</dd>

<dt>xdr</dt> <dd>Defines the transport to be used for cross-domain requests. By setting this property, the transaction will use the specified transport instead of XMLHttpRequest. The properties of the transport object are: <dl> <dt>use</dt> <dd>The transport to be used: 'flash' or 'native'</dd> <dt>dataType</dt> <dd>Set the value to 'XML' if that is the expected response content type.</dd> <dt>credentials</dt> <dd>Set the value to 'true' to set XHR.withCredentials property to true.</dd> </dl></dd>

<dt>form</dt> <dd>Form serialization configuration object. Its properties are: <dl> <dt>id</dt> <dd>Node object or id of HTML form</dd> <dt>useDisabled</dt> <dd>true to also serialize disabled form field values (defaults to false)</dd> </dl></dd>

<dt>on</dt> <dd>Assigns transaction event subscriptions. Available events are: <dl> <dt>start</dt> <dd>Fires when a request is sent to a resource.</dd> <dt>complete</dt> <dd>Fires when the transaction is complete.</dd> <dt>success</dt> <dd>Fires when the HTTP response status is within the 2xx range.</dd> <dt>failure</dt> <dd>Fires when the HTTP response status is outside the 2xx range, if an exception occurs, if the transation is aborted, or if the transaction exceeds a configured timeout.</dd> <dt>end</dt> <dd>Fires at the conclusion of the transaction lifecycle, after success or failure.</dd> </dl>

<p>Callback functions for start and end receive the id of the
                                                transaction as a first argument. For complete, success, and
                                                failure, callbacks receive the id and the response object
                                                (usually the XMLHttpRequest instance).  If the arguments
                                                property was included in the configuration object passed to
                                                Y.io(), the configured data will be passed to all callbacks as
                                                the last argument.</p>
                                                </dd>
                                                

<dt>sync</dt> <dd>Pass true to make a same-domain transaction synchronous. <strong>CAVEAT</strong>: This will negatively impact the user experience. Have a <em>very</em> good reason if you intend to use this.</dd>

<dt>context</dt> <dd>The "this'" object for all configured event handlers. If a specific context is needed for individual callbacks, bind the callback to a context usingY.bind()`.</dd>

<dt>headers</dt> <dd>Object map of transaction headers to send to the server. The object keys are the header names and the values are the header values.</dd>

<dt>username</dt> <dd>Username to use in a HTTP authentication.</dd>

<dt>password</dt> <dd>Password to use in a HTTP authentication.</dd>

<dt>timeout</dt> <dd>Millisecond threshold for the transaction before being automatically aborted.</dd>

<dt>arguments</dt> <dd>User-defined data passed to all registered event handlers. This value is available as the second argument in the "start" and "end" event handlers. It is the third argument in the "complete", "success", and "failure" event handlers. <strong>Be sure to quote this property name in the transaction configuration as "arguments" is a reserved word in JavaScript</strong> (e.g. Y.io({ ..., "arguments": stuff })).</dd> </dl>

Parameters:

  • uri String

    Qualified path to transaction resource.

  • config Object

    Configuration object for the transaction.

  • id Number

    Transaction id, if already set.

Returns:

Object:

An object containing: <dl> <dt>id</dt> <dd> The transaction ID for this request. </dd> <dt>abort</dt> <dd> A function to abort the current transaction. </dd> <dt>isInProgress</dt> <dd> A helper to determine whether the current transaction is in progress. </dd> <dt>io</dt> <dd> A reference to the IO object for this transaction. </dd> </dl>

setHeader

(
  • name
  • value
)

Stores default client headers for all transactions. If a label is passed with no value argument, the header will be deleted.

Parameters:

  • name String

    HTTP header

  • value String

    HTTP header value

start

(
  • transaction
  • config
)

Fires event "io:start" and creates, fires a transaction-specific start event, if config.on.start is defined.

Parameters:

  • transaction Object

    Transaction object.

  • config Object

    Configuration object for the transaction.

stringify

(
  • form
  • [options]
)
String static

Provided by the io-form module.

Defined in yui3/src/io/js/io-form.js:11

Enumerate through an HTML form's elements collection and return a string comprised of key-value pairs.

Parameters:

  • form Node | String

    YUI form node or HTML form id

  • [options] Object optional

    Configuration options.

    • [useDisabled=false] Boolean optional

      Whether to include disabled fields.

    • [extra] Object | String optional

      Extra values to include. May be a query string or an object with key/value pairs.

Returns:

String:

success

(
  • transaction
  • config
)

Fires event "io:success" and creates, fires a transaction-specific "success" event, if config.on.success is defined.

Parameters:

  • transaction Object

    Transaction object.

  • config Object

    Configuration object for the transaction.

transport

(
  • o
)

Provided by the io-xdr module.

Defined in yui3/src/io/js/io-xdr.js:264

Initializes the desired transport.

Parameters:

  • o Object
    • object of transport configurations.

transports.nodejs

() Object static

Provided by the io-nodejs module.

Defined in yui3/src/io/js/io-nodejs.js:41

NodeJS IO transport, uses the NodeJS <a href="https://github.com/mikeal/request">request</a> module under the hood to perform all network IO.

Returns:

Object:

This object contains only a send method that accepts a transaction object, uri and the config object.

Example:

Y.io('https://somedomain.com/url', {
                                                    method: 'PUT',
                                                    data: '?foo=bar',
                                                    //Extra request module config options.
                                                    request: {
                                                        maxRedirects: 100,
                                                        strictSSL: true,
                                                        multipart: [
                                                            {
                                                                'content-type': 'application/json',
                                                                body: JSON.stringify({
                                                                    foo: 'bar',
                                                                    _attachments: {
                                                                        'message.txt': {
                                                                            follows: true,
                                                                            length: 18,
                                                                            'content_type': 'text/plain'
                                                                        }
                                                                    }
                                                                })
                                                            },
                                                            {
                                                                body: 'I am an attachment'
                                                            }
                                                        ]
                                                    },
                                                    on: {
                                                        success: function(id, e) {
                                                            Y.log(e.responseText);
                                                        }
                                                    }
                                                });

xdr

(
  • uri
  • o
  • c
)

Provided by the io-xdr module.

Defined in yui3/src/io/js/io-xdr.js:157

Method for accessing the transport's interface for making a cross-domain transaction.

Parameters:

  • uri String
    • qualified path to transaction resource.
  • o Object
    • Transaction object generated by _create() in io-base.
  • c Object
    • configuration object for the transaction.

xdrReady

(
  • yid
  • uid
)
protected static

Provided by the io-xdr module.

Defined in yui3/src/io/js/io-xdr.js:278

Fires event "io:xdrReady"

Parameters:

xdrResponse

(
  • e
  • o
  • c
)
Object

Provided by the io-xdr module.

Defined in yui3/src/io/js/io-xdr.js:212

Response controller for cross-domain requests when using the Flash transport or IE8's XDomainRequest object.

Parameters:

  • e String

    Event name

  • o Object

    Transaction object generated by _create() in io-base.

  • c Object

    Configuration object for the transaction.

Returns:

Object:

Properties

_cB

Object private

Provided by the io-xdr module.

Defined in yui3/src/io/js/io-xdr.js:20

Map of stored configuration objects when using Flash as the transport for cross-domain requests.

_headers

Object private

Object of IO HTTP headers sent with each transaction.

_id

Number private

A counter that increments for each transaction.

_q

Object private static

Provided by the io-queue module.

Defined in yui3/src/io/js/io-queue.js:11

Array of transactions queued for processing

_qState

Number private static

Provided by the io-queue module.

Defined in yui3/src/io/js/io-queue.js:23

Property to determine whether the queue is set to 1 (active) or 0 (inactive). When inactive, transactions will be stored in the queue until the queue is set to active.

_rS

Object private

Provided by the io-xdr module.

Defined in yui3/src/io/js/io-xdr.js:30

Map of transaction simulated readyState values when XDomainRequest is the transport.

_timeout

Object private

Object that stores timeout values for any transaction with a defined "timeout" configuration property.

_transport

Object private

Provided by the io-xdr module.

Defined in yui3/src/io/js/io-xdr.js:118

Map of io transports.

delay

Number static

Provided by the io-xdr module.

Defined in yui3/src/io/js/io-xdr.js:304

Delay value to calling the Flash transport, in the event io.swf has not finished loading. Once the E_XDR_READY event is fired, this value will be set to 0.

Events

io:complete

Signals the completion of the request-response phase of a transaction. Response status and data are accessible, if available, in this event.

io:end

Signals the end of the transaction lifecycle.

io:failure

Signals an HTTP response with status outside of the 2xx range. Fires after io:complete.

io:progress

Signals the interactive state during a file upload transaction. This event fires after io:start and before io:complete.

io:start

Signals the start of an IO request.

io:success

Signals an HTTP response with status in the 2xx range. Fires after io:complete.

io:xdrReady

Provided by the io-xdr module.

Defined in yui3/src/io/js/io-xdr.js:14

Fires when the XDR transport is ready for use.