# Yahoo! UI Library

### io 3.0.0

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.

#### _rS - `private static object`

Map of transaction state used when XDomainRequest is the XDR transport.

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

#### _abort

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

#### _clearTimeout

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

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

Returns: ``
  void

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

Returns: ``
  int

#### _create

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

Parameters:
  `c <number>` - configuration object subset to determine if the transaction is an XDR or file upload, requiring an alternate transport.
  `i <number>` - transaction id

Returns: ``
  object

#### _data

`private static _data ( o , isFlash , isXML )`
Creates a response object for XDR transactions, for success and failure cases.

Parameters:
  `o <object>` - Transaction object generated by _create() in io-base.
  `isFlash <boolean>` - True if Flash was used as the transport.
  `isXML <boolean>` - True if the response data are XML.

Returns: ``
  object

#### _destroy

`private static void _destroy ( o , uri , c )`

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

#### _handle

`private static void _handle ( o , c )`
Bound to the iframe's Load event and processes the response data.

Parameters:
  `o <o>` The transaction object
  `c <object>` Configuration object for the transaction.

#### _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().

Returns: ``
  void

#### _id

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

Returns: ``
  int

#### _io

`private static _io ( uri , c , i )`
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.
  `i <number>` - transaction id, if already set by queue.

Returns: ``
  object

#### _ioCancel

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

Parameters:
  `o <object>` - Transaction object generated by _create().
  `s <string>` - Identifies timed out or aborted transaction.

Returns: ``
  void

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

Returns: ``
  void

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

Returns: ``
  void

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

Returns: ``
  void

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

Returns: ``
  void

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

Returns: ``
  void

#### _isInProgress.

`private static void _isInProgress. ( o , c )`
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.
  `c <object>` - configuration object for the transaction.

#### _queue

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

Returns: ``
  Object

#### _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().

Returns: ``
  void

#### _remove

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

Returns: ``
  void

#### _resend

`private static _resend ( o , uri , c )`
Resends an XDR transaction, using the Flash tranport, if the native transport fails.

Parameters:
  `o <object>` - Transaction object generated by _create().
  `uri <string>` - qualified path to transaction resource.
  `c <object>` - configuration object for the transaction.

Returns: ``
  void

#### _resetAttrs

`private static void _resetAttrs ( f , a )`
Sets the appropriate attributes and values to the HTML form, in preparation of a file upload transaction.

Parameters:
  `f <object>` HTML form object.
  `a <object>` Object of original attributes.

#### _serialize

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

Parameters:
  `c <object>` - YUI form node or HTML form id.
  `s <string>` - Transaction data defined in the configuration.

Returns: ``
  string

#### _setAttrs

`private static void _setAttrs ( f , id , uri )`
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.

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

Returns: ``
  int

#### _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().

Returns: ``
  void

#### _shift

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

Returns: ``
  void

#### _size

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

Returns: ``
  int

#### _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().

Returns: ``
  void

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

Returns: ``
  void

#### _subscribe

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

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

Returns: ``
  void

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

Returns: ``
  void

#### _unshift

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

Returns: ``
  void

#### _upload

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

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

#### _xdr

`private static _xdr ( o , c )`
Sets event handlers for XDomainRequest transactions.

Parameters:
  `o <object>` - Transaction object generated by _create() in io-base.
  `c <object>` - configuration object for the transaction.

Returns: ``
  void

#### _xhr

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

Returns: ``
  object

#### appendData

`private static array appendData ( f , s )`
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`
  e Array of created fields.

#### f

`private static void f ( f , o )`
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.

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

Returns: ``
  int

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

Returns: ``
  object

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

Returns: ``
  void

#### remove

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

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

Returns: ``
  void

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

Returns: ``
  number

#### 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().

Returns: ``
  void

#### 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().

Returns: ``
  void

#### transport

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

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

Returns: ``
  void

#### xdrReady

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

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

Returns: ``
  void

#### xdrResponse

`private static xdrResponse ( o , c , e )`
Response controller for cross-domain requests when using the Flash transport or IE8's XDomainRequest object.

Parameters:
  `o <object>` - Transaction object generated by _create() in io-base.
  `c <object>` - configuration object for the transaction.
  `e <string>` - Event name

Returns: ``
  object

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