#

API Docs for: 3.10.3
Show: Inherited Protected Private Deprecated

# IO Class

Defined in: `io/js/io-base.js:18`
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`

)

Defined in `io/js/io-base.js:18`

#### Parameters:

- `config` Object

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

- Index
- Methods
- Properties
- Events

## Item Index

### Methods

- _abort
- _abort
- _cFrame
- _clearTimeout
- _clearUploadTimeout static
- _concat
- _create
- _data
- _dFrame
- _evt
- _ieEvt static
- _isInProgress
- _qShift static
- _removeData static
- _resetAttrs static
- _result static
- _retry
- _rS
- _serialize
- _setAttrs static
- _setHeaders
- _size static
- _startTimeout
- _startUploadTimeout static
- _stop static
- _swf
- _upload static
- _uploadComplete static
- _xdrReady
- appendData static
- complete
- empty static
- end
- error
- failure
- flatten
- load
- progress
- promote static
- queue static
- remove static
- request static
- send
- setHeader
- start
- stringify static
- success
- transport
- transports.nodejs static
- xdr
- xdrReady static
- xdrResponse

### Properties

- _cB
- _headers
- _id
- _q static
- _qState static
- _rS
- _timeout
- _transport
- delay static

### Events

- io:complete
- io:end
- io:failure
- io:progress
- io:start
- io:success
- io:xdrReady

## Methods

### `_abort`

(

- `o`
- `c`

)
private

Provided by the io-xdr module.

Defined in `io/js/io-xdr.js:91`

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

Defined in `io/js/io-base.js:516`

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.

### `_cFrame`

(

- `o`
- `c`
- `io`

)
private

Provided by the io-upload-iframe module.

Defined in `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

Defined in `io/js/io-base.js:451`

Clears the timeout interval started by _startTimeout().

#### Parameters:

- `id` Number
  - Transaction id.

### `_clearUploadTimeout`

(

- `id`

)
private static

Provided by the io-upload-iframe module.

Defined in `io/js/io-upload-iframe.js:159`

Clears the timeout interval started by _startUploadTimeout().

#### Parameters:

- `id` Number
  - Transaction ID.

### `_concat`

(

- `uri`
- `data`

)
String private

Defined in `io/js/io-base.js:386`

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

Defined in `io/js/io-base.js:94`

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 `io/js/io-xdr.js:68`

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 `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

Defined in `io/js/io-base.js:170`

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 `io/js/io-xdr.js:126`

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 `io/js/io-xdr.js:103`

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 `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 `io/js/io-upload-iframe.js:83`

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 `io/js/io-upload-iframe.js:117`

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

Defined in `io/js/io-base.js:463`

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

Defined in `io/js/io-base.js:370`

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

Defined in `io/js/io-base.js:492`

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 `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 `io/js/io-upload-iframe.js:100`

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

Defined in `io/js/io-base.js:416`

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 `io/js/io-queue.js:144`

Method to query the current size of the queue.

#### Returns:

Number:

### `_startTimeout`

(

- `transaction`
- `timeout`

)
private

Defined in `io/js/io-base.js:434`

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 `io/js/io-upload-iframe.js:136`

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 `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`
- `yid`

)
private

Provided by the io-xdr module.

Defined in `io/js/io-xdr.js:46`

Method that creates the Flash transport swf.

#### Parameters:

- `uri` String
  - location of io.swf.
- `yid` String
  - YUI sandbox id.
- `yid` String
  - IO instance id.

### `_upload`

(

- `o`
- `uri`
- `c`

)
private static

Provided by the io-upload-iframe module.

Defined in `io/js/io-upload-iframe.js:217`

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 `io/js/io-upload-iframe.js:173`

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 `io/js/io-xdr.js:251`

Fires event "io:xdrReady"

#### Parameters:

- `yid` Number
  - YUI sandbox id.
- `uid` Number
  - IO instance id.

### `appendData`

(

- `f`
- `s`

)
Array private static

Provided by the io-upload-iframe module.

Defined in `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.

### `complete`

(

- `transaction`
- `config`

)

Defined in `io/js/io-base.js:248`

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 `io/js/io-queue.js:108`

Available since 3.7.3

Method for cancel all pending transaction from the queue.

### `end`

(

- `transaction`
- `config`

)

Defined in `io/js/io-base.js:267`

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`

)

Defined in `io/js/io-base.js:355`

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`

)

Defined in `io/js/io-base.js:302`

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 `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`

)

Defined in `io/js/io-base.js:340`

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`

)

Defined in `io/js/io-base.js:320`

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 `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 `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 `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 `io/js/io-nodejs.js:7`

Passthru to the NodeJS request 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

Defined in `io/js/io-base.js:531`

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

method
  HTTP method verb (e.g., GET or POST). If this property is not not defined, the default value will be GET.
data
  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.
xdr
  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:
  use
    The transport to be used: 'flash' or 'native'
  dataType
    Set the value to 'XML' if that is the expected response content type.
  credentials
    Set the value to 'true' to set XHR.withCredentials property to true.
form
  Form serialization configuration object. Its properties are:
  id
    Node object or id of HTML form
  useDisabled
    `true` to also serialize disabled form field values (defaults to `false`)
on
  Assigns transaction event subscriptions. Available events are:
  start
    Fires when a request is sent to a resource.
  complete
    Fires when the transaction is complete.
  success
    Fires when the HTTP response status is within the 2xx range.
  failure
    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`.
  end
    Fires at the conclusion of the transaction lifecycle, after `success` or `failure`.

  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.

sync
  Pass `true` to make a same-domain transaction synchronous. CAVEAT: This will negatively impact the user experience. Have a very good reason if you intend to use this.
context
  The "`this'" object for all configured event handlers. If a specific context is needed for individual callbacks, bind the callback to a context using `Y.bind()`.
headers
  Object map of transaction headers to send to the server. The object keys are the header names and the values are the header values.
timeout
  Millisecond threshold for the transaction before being automatically aborted.
arguments
  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. Be sure to quote this property name in the transaction configuration as "arguments" is a reserved word in JavaScript (e.g. `Y.io({ ..., "arguments": stuff })`).

#### Parameters:

- `uri` String

  Qualified path to transaction resource.

- `config` Object

  Configuration object for the transaction.

- `id` Number

  Transaction id, if already set.

#### Returns:

Object:

### `setHeader`

(

- `name`
- `value`

)

Defined in `io/js/io-base.js:400`

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`

)

Defined in `io/js/io-base.js:232`

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 `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`

)

Defined in `io/js/io-base.js:284`

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 `io/js/io-xdr.js:263`

Initializes the desired transport.

#### Parameters:

- `o` Object
  - object of transport configurations.

### `transports.nodejs`

() Object static

Provided by the io-nodejs module.

Defined in `io/js/io-nodejs.js:41`

NodeJS IO transport, uses the NodeJS request 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 `io/js/io-xdr.js:156`

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 `io/js/io-xdr.js:277`

Fires event "io:xdrReady"

#### Parameters:

- `yid` Number
  - YUI sandbox id.
- `uid` Number
  - IO instance id.

### `xdrResponse`

(

- `e`
- `o`
- `c`

)
Object

Provided by the io-xdr module.

Defined in `io/js/io-xdr.js:211`

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 `io/js/io-xdr.js:19`

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

### `_headers`

Object private

Defined in `io/js/io-base.js:52`

Object of IO HTTP headers sent with each transaction.

### `_id`

Number private

Defined in `io/js/io-base.js:43`

A counter that increments for each transaction.

### `_q`

Object private static

Provided by the io-queue module.

Defined in `io/js/io-queue.js:11`

Array of transactions queued for processing

### `_qState`

Number private static

Provided by the io-queue module.

Defined in `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 `io/js/io-xdr.js:29`

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

### `_timeout`

Object private

Defined in `io/js/io-base.js:63`

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 `io/js/io-xdr.js:117`

Map of io transports.

### `delay`

Number static

Provided by the io-xdr module.

Defined in `io/js/io-xdr.js:303`

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

## Events

### `io:complete`

Defined in `io/js/io-base.js:258`

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

### `io:end`

Defined in `io/js/io-base.js:276`

Signals the end of the transaction lifecycle.

### `io:failure`

Defined in `io/js/io-base.js:311`

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

### `io:progress`

Defined in `io/js/io-base.js:331`

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

### `io:start`

Defined in `io/js/io-base.js:241`

Signals the start of an IO request.

### `io:success`

Defined in `io/js/io-base.js:293`

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

### `io:xdrReady`

Provided by the io-xdr module.

Defined in `io/js/io-xdr.js:13`

Fires when the XDR transport is ready for use.