# Yahoo! UI Library

### io 3.0.0b1

Yahoo! UI Library > io > io
Search:
Filters Show Private Show Protected Show Deprecated

## Class 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. YUI.io can also use Flash, if specified as a transport, for cross-domain requests.

### Properties

#### _e - `private static Object`

Reference to "io:complete" event handler.

#### _fn - `private static object`

Object that stores callback handlers for cross-domain requests when using Flash as the transport.

#### _headers - `private static object`

Object of default HTTP headers to be initialized and sent for all transactions.

#### _qState - `private static int`

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.

#### _timeOut - `private static object`

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

#### _transport - `private static object`

Map of IO transports.

#### _yQ - `private static Object`

Array of transactions queued for processing

#### transactionId - `private static int`

A transaction counter that increments for each transaction.

### Methods

#### _async

`private static _async ( o , d , c )`
Method that sends the transaction request.

Parameters:
  `o <object>` - Transaction object generated by _create().
  `d <string>` - Transaction data.
  `c <object>` - Configuration object passed to YUI.io().

#### _clearTimeout

`private static _clearTimeout ( id )`
Clears the timeout interval started by _startTimeout().

Parameters:
  `id <number>` - Transaction id.

#### _concat

`private static _concat ( s , d )`
Method that concatenates string data for HTTP GET transactions.

Parameters:
  `s <string>` - URI or root data.
  `d <string>` - data to be concatenated onto URI.

#### _create

`private static _create ( s , c )`
Method that creates a unique transaction object for each request.

Parameters:
  `s <number>` - URI or root data.
  `c <number>` - configuration object

#### _handleResponse

`private static _handleResponse ( o , c )`
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:
  `o <object>` - Transaction object generated by _create().
  `c <object>` - Configuration object passed to io().

#### _id

`private static _id ( )`
Method that increments _transactionId for each transaction.

#### _io

`private static _io ( uri , c )`
Method for requesting a transaction. _io() is implemented as yui.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. Currently, the only alternate transport supported is Flash (e.g., { xdr: 'flash' }). form: This is a defined object used to process HTML form as data. The properties are: { id: object, //HTML form object or id of HTML form useDisabled: boolean, //Allow disabled HTML form field values to be sent as part of the data. } on: This is a defined object used to create and handle specific events during a transaction lifecycle. These events will fire in addition to the global io events. The events are: start - This event is fired when a request is sent to a resource. complete - This event fires when the transaction is complete. success - This event fires when the response status resolves to HTTP 2xx. failure - This event fires when the response status resolves to HTTP 4xx, 5xx; and, for all transaction exceptions, including aborted transactions and transaction timeouts. end - This even is fired at the conclusion of the transaction lifecycle, after a success or failure resolution. The properties are: { start: function(id, args){}, complete: function(id, responseobject, args){}, success: function(id, responseobject, args){}, failure: function(id, responseobject, args){}, end: function(id, args){} } Each property can reference a function or be written as an inline function. context: Object reference for an event handler when it is implemented as a method of a base object. Defining "context" will preserve the proper reference of "this" used in the event handler. headers: This is a defined object of client headers, as many as. desired for the transaction. These headers are sentThe object pattern is: { header: value } timeout: This value, defined as milliseconds, is a time threshold for the transaction. When this threshold is reached, and the transaction's Complete event has not yet fired, the transaction will be aborted. arguments: Object, array, string, or number passed to all registered event handlers. This value is available as the second argument in the "start" and "abort" event handlers; and, it is the third argument in the "complete", "success", and "failure" event handlers.

Parameters:
  `uri <string>` - qualified path to transaction resource.
  `c <object>` - configuration object for the transaction.

#### _ioCancel

`private static _ioCancel ( o , c , s )`
Terminates a transaction due to an explicit abort or timeout.

Parameters:
  `o <object>` - Transaction object generated by _create().
  `c <object>` - Configuration object passed to YUI.io().
  `s <string>` - Identifies timed out or aborted transaction.

#### _ioComplete

`private static _ioComplete ( o , c )`
Fires event "io:complete" and creates, fires a transaction-specific "complete" event, if config.on.complete is defined.

Parameters:
  `o <object>` - transaction object.
  `c <object>` - configuration object for the transaction.

#### _ioEnd

`private static _ioEnd ( o , c )`
Fires event "io:end" and creates, fires a transaction-specific "end" event, if config.on.end is defined.

Parameters:
  `o <object>` - transaction object.
  `c <object>` - configuration object for the transaction.

#### _ioFailure

`private static _ioFailure ( o , c )`
Fires event "io:failure" and creates, fires a transaction-specific "failure" event, if config.on.failure is defined.

Parameters:
  `o <object>` - transaction object.
  `c <object>` - configuration object for the transaction.

#### _ioStart

`private static _ioStart ( id , c )`
Fires event "io:start" and creates, fires a transaction-specific start event, if config.on.start is defined.

Parameters:
  `id <number>` - transaction id
  `c <object>` - configuration object for the transaction.

#### _ioSuccess

`private static _ioSuccess ( o , c )`
Fires event "io:success" and creates, fires a transaction-specific "success" event, if config.on.success is defined.

Parameters:
  `o <object>` - transaction object.
  `c <object>` - configuration object for the transaction.

#### _isInProgress

`private static _isInProgress ( o )`
Determines if a cross-domain transaction is still in progress.

Parameters:
  `o <object>` - Transaction object generated by _create().

#### _queue

`private static _queue ( )`
Method for requesting a transaction, and queueing the request before it is sent to the resource.

#### _readyState

`private static _readyState ( o , c )`
Event handler bound to onreadystatechange.

Parameters:
  `o <object>` - Transaction object generated by _create().
  `c <object>` - Configuration object passed to YUI.io().

#### _remove

`private static _remove ( )`
Method for removing a specific, pending transaction from the queue.

#### _serialize

`private static _serialize ( o )`
Method to enumerate through an HTML form's elements collection and return a string comprised of key-value pairs.

Parameters:
  `o <object>` - YUI form node or HTML form id.

#### _setHeader

`private static _setHeader ( l , v )`
Method that stores default client headers for all transactions. If a label is passed with no value argument, the header will be deleted.

Parameters:
  `l <string>` - HTTP header
  `v <string>` - HTTP header value

#### _setHeaders

`private static _setHeaders ( o , h )`
Method that sets all HTTP headers to be sent in a transaction.

Parameters:
  `o <object>` - XHR instance for the specific transaction.
  `h <object>` - HTTP headers for the specific transaction, as defined in the configuration object passed to YUI.io().

#### _shift

`private static _shift ( )`
Method Process the first transaction from the queue in FIFO order.

#### _size

`private static _size ( )`
Method to query the current size of the queue.

#### _startTimeout

`private static _startTimeout ( o , c )`
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 _stop ( )`
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

`private static _swf ( uri , yid )`
Method that creates the Flash transport swf.

Parameters:
  `uri <string>` - location of IO.swf.
  `yid <string>` - YUI instance id.

#### _tPubSub

`private static _tPubSub ( e , c )`
Method for creating and subscribing transaction events.

Parameters:
  `e <string>` - event to be published
  `c <object>` - configuration data subset for event subscription.

#### _unshift

`private static _unshift ( )`
Method for promoting a transaction to the top of the queue.

#### _upload

`private static void _upload ( o , uri , c )`
Uploads HTML form, inclusive of files/attachments, using the iframe created in createFrame to facilitate the transaction.

Parameters:
  `o <o>` The transaction object
  `uri <object>` Qualified path to transaction resource.
  `c <object>` Configuration object for the transaction.

Returns: `void`

#### _xdr

`private static _xdr ( uri , o , c )`
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.

#### _xhr

`private static _xhr ( )`
Method that creates the XMLHttpRequest transport

#### appendData

`private static array appendData ( d )`
Parses the POST data object and creates hidden form elements for each key-value, and appends them to the HTML form object.

Parameters:
  `d <object>` The key-value hash map.

Returns: `array`
  e Array of created fields.

#### header

`static header ( l , v )`
Method that stores default client headers for all transactions. If a label is passed with no value argument, the header will be deleted. This is the interface for _setHeader().

Parameters:
  `l <string>` - HTTP header
  `v <string>` - HTTP header value

#### io

`static io ( uri , c )`
Method for requesting a transaction. This is the interface for _io().

Parameters:
  `uri <string>` - qualified path to transaction resource.
  `c <object>` - configuration object for the transaction.

#### promote

`static promote ( o )`
Method for promoting a transaction to the top of the queue. This is the interface for _unshift().

Parameters:
  `o <Object>` - Reference to queued transaction.

#### purge

`static purge ( o )`
Method for removing a specific, pending transaction from the queue. This is the interface for _purge().

Parameters:
  `o <Object>` - Reference to queued transaction.

#### size

`static size ( i )`
Method to query the current size of the queue, or to set a maximum queue size. This is the interface for _size().

Parameters:
  `i <number>` - Specified maximum size of queue.

#### start

`static start ( )`
Method for setting the queue to active. If there are transactions pending in the queue, they will be processed from the queue in FIFO order. This is the interface for _start().

#### stop

`static stop ( )`
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 restarted. This is the interface for _stop().

#### transport

`static transport ( o )`
Method to initialize the desired transport.

Parameters:
  `o <object>` - object of transport configurations.

#### xdrReady

`private static xdrReady ( id , c )`
Fires event "io:xdrReady"

Parameters:
  `id <number>` - transaction id
  `c <object>` - configuration object for the transaction.

### Events

#### io:complete

`io:complete ( )`
This event is fired by YUI.io when a transaction is complete. Response status and data are accessible, if available.

#### io:end

`io:end ( )`
This event signifies the end of the transaction lifecycle. The transaction transport is destroyed.

#### io:failure

`io:failure ( )`
This event is fired by YUI.io when a transaction is complete, and the HTTP status resolves to HTTP4xx, 5xx and above.

#### io:start

`io:start ( )`
This event is fired by YUI.io when a transaction is initiated.

#### io:success

`io:success ( )`
This event is fired by YUI.io when a transaction is complete, and the HTTP status resolves to HTTP2xx.

#### io:xdrReady

`io:xdrReady ( )`
This event is fired by YUI.io when the specified transport is ready for use.

Copyright © 2009 Yahoo! Inc. All rights reserved.