IO Class
+ + + + +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.
+
+
+
-
+
- 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
+ + +Events
+ +-
+
+
- + io:complete + + + + + +
- + io:end + + + + + +
- + io:failure + + + + + +
- + io:progress + + + + + +
- + io:start + + + + + +
- + io:success + + + + + +
- + io:xdrReady + + + + + +
Methods
+ + +_abort
+
+
+ -
+
+
-
+
+
o+ +
+
+ -
+
+
c+ +
+
+
Method for intiating an XDR transaction abort.
+_abort
+
+
+ -
+
+
-
+
+
transaction+ +
+
+ -
+
+
type+ +
+
+
Terminates a transaction due to an explicit abort or timeout.
+_cFrame
+
+
+ -
+
+
-
+
+
o+ +
+
+ -
+
+
c+ +
+
+ -
+
+
io+ +
+
+
Creates the iframe transported used in file upload +transactions, and binds the response event handler.
+_clearTimeout
+
+
+ -
+
+
-
+
+
id+ +
+
+
Clears the timeout interval started by _startTimeout().
+Parameters:
+ +-
+
+
-
+
+
id+ Number + + + + +++ + +-
+
- Transaction id. +
+
+
_clearUploadTimeout
+
+
+ -
+
+
-
+
+
id+ +
+
+
Clears the timeout interval started by _startUploadTimeout().
+Parameters:
+ +-
+
+
-
+
+
id+ Number + + + + +++ + +-
+
- Transaction ID. +
+
+
_concat
+
+
+ -
+
+
-
+
+
uri+ +
+
+ -
+
+
data+ +
+
+
Method that concatenates string data for HTTP GET transactions.
+Parameters:
+ + +Returns:
+ +_create
+
+
+ -
+
+
-
+
+
cfg+ +
+
+ -
+
+
id+ +
+
+
Method that creates a unique transaction object for each request.
+Parameters:
+ + +Returns:
+ +_data
+
+
+ -
+
+
-
+
+
o+ +
+
+ -
+
+
u+ +
+
+ -
+
+
d+ +
+
+
Creates a response object for XDR transactions, for success +and failure cases.
+Parameters:
+ + +Returns:
+ +_dFrame
+
+
+ -
+
+
-
+
+
id+ +
+
+
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+ +
+
+
Method for creating and firing events.
+_ieEvt
+
+
+ -
+
+
-
+
+
o+ +
+
+ -
+
+
c+ +
+
+
Sets event handlers for XDomainRequest transactions.
+_isInProgress
+
+
+ -
+
+
-
+
+
o+ +
+
+
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
+
+
+
+
+
+
+
+
+ Method Process the first transaction from the +queue in FIFO order.
+_removeData
+
+
+ -
+
+
-
+
+
f+ +
+
+ -
+
+
o+ +
+
+
Removes the custom fields created to pass additional POST +data, along with the HTML form fields.
+_resetAttrs
+
+
+ -
+
+
-
+
+
f+ +
+
+ -
+
+
a+ +
+
+
Reset the HTML form attributes to their original values.
+_result
+
+
+ -
+
+
-
+
+
transaction+ +
+
+ -
+
+
config+ +
+
+
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.
+_retry
+
+
+ -
+
+
-
+
+
transaction+ +
+
+ -
+
+
uri+ +
+
+ -
+
+
config+ +
+
+
Retry an XDR transaction, using the Flash tranport, if the native +transport fails.
+_rS
+
+
+ -
+
+
-
+
+
transaction+ +
+
+ -
+
+
config+ +
+
+
Event handler bound to onreadystatechange.
+_serialize
+
+
+ -
+
+
-
+
+
c+ +
+
+ -
+
+
s+ +
+
+
Enumerate through an HTML form's elements collection +and return a string comprised of key-value pairs.
+Parameters:
+ + +Returns:
+ +_setAttrs
+
+
+ -
+
+
-
+
+
f+ +
+
+ -
+
+
id+ +
+
+ -
+
+
uri+ +
+
+
Sets the appropriate attributes and values to the HTML +form, in preparation of a file upload transaction.
+_setHeaders
+
+
+ -
+
+
-
+
+
transaction+ +
+
+ -
+
+
headers+ +
+
+
Method that sets all HTTP headers to be sent in a transaction.
+_size
+
+
+ ()
+
+
+
+
+ Number
+
+
+
+
+
+
+ private
+
+
+
+
+
+ static
+
+
+
+
+
+
+
+
+ Method to query the current size of the queue.
+Returns:
+ +_startTimeout
+
+
+ -
+
+
-
+
+
transaction+ +
+
+ -
+
+
timeout+ +
+
+
Starts timeout count if the configuration object has a defined +timeout property.
+_startUploadTimeout
+
+
+ -
+
+
-
+
+
o+ +
+
+ -
+
+
c+ +
+
+
Starts timeout count if the configuration object +has a defined timeout property.
+_stop
+
+
+ ()
+
+
+
+
+
+
+
+ private
+
+
+
+
+
+ static
+
+
+
+
+
+
+
+
+ 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+ +
+
+
Method that creates the Flash transport swf.
+_upload
+
+
+ -
+
+
-
+
+
o+ +
+
+ -
+
+
uri+ +
+
+ -
+
+
c+ +
+
+
Uploads HTML form data, inclusive of files/attachments, +using the iframe created in _create to facilitate the transaction.
+_uploadComplete
+
+
+ -
+
+
-
+
+
o+ +
+
+ -
+
+
c+ +
+
+
Bound to the iframe's Load event and processes +the response data.
+_xdrReady
+
+
+ -
+
+
-
+
+
yid+ +
+
+ -
+
+
uid+ +
+
+
Fires event "io:xdrReady"
+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:
+ + +Returns:
+ +complete
+
+
+ -
+
+
-
+
+
transaction+ +
+
+ -
+
+
config+ +
+
+
Fires event "io:complete" and creates, fires a +transaction-specific "complete" event, if config.on.complete is +defined.
+empty
+
+
+ ()
+
+
+
+
+
+
+
+
+
+
+
+ static
+
+
+
+
+
+
+
+
+ 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.
+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.
+failure
+
+
+ -
+
+
-
+
+
transaction+ +
+
+ -
+
+
config+ +
+
+
Fires event "io:failure" and creates, fires a transaction-specific +"failure" event, if config.on.failure is defined.
+flatten
+
+
+ -
+
+
-
+
+
o+ +
+
+
Flatten headers object
+Parameters:
+ +-
+
+
-
+
+
o+ Object + + + + +++ + +The headers object
+
+
+
Returns:
+ +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.
+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.
+promote
+
+
+ ()
+
+
+
+
+
+
+
+
+
+
+
+ static
+
+
+
+
+
+
+
+
+ Method for promoting a transaction to the top of the queue.
+queue
+
+
+ ()
+
+
+
+
+ Object
+
+
+
+
+
+
+
+
+
+
+ static
+
+
+
+
+
+
+
+
+ Method for queueing a transaction before the request is sent to the +resource, to ensure sequential processing.
+Returns:
+ +remove
+
+
+ ()
+
+
+
+
+
+
+
+ private
+
+
+
+
+
+ static
+
+
+
+
+
+
+
+
+ Method for removing a specific, pending transaction from +the queue.
+request
+
+
+ ()
+
+
+
+
+
+
+
+
+
+
+
+ static
+
+
+
+
+
+
+
+
+ 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+ +
+
+
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 +
trueto also serialize disabled form field values + (defaults tofalse)
+
+
+ - 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
successorfailure.
+
Callback functions for
+startandendreceive the id of the + transaction as a first argument. Forcomplete,success, and +failure, callbacks receive the id and the response object + (usually the XMLHttpRequest instance). If thearguments+ 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
trueto 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:
+ + +Returns:
+ +setHeader
+
+
+ -
+
+
-
+
+
name+ +
+
+ -
+
+
value+ +
+
+
Stores default client headers for all transactions. If a label is +passed with no value argument, the header will be deleted.
+start
+
+
+ -
+
+
-
+
+
transaction+ +
+
+ -
+
+
config+ +
+
+
Fires event "io:start" and creates, fires a transaction-specific
+start event, if config.on.start is defined.
stringify
+
+
+ -
+
+
-
+
+
form+ +
+
+ -
+
+
[options]+ +
+
+
Enumerate through an HTML form's elements collection +and return a string comprised of key-value pairs.
+Parameters:
+ + +Returns:
+ +success
+
+
+ -
+
+
-
+
+
transaction+ +
+
+ -
+
+
config+ +
+
+
Fires event "io:success" and creates, fires a transaction-specific +"success" event, if config.on.success is defined.
+transport
+
+
+ -
+
+
-
+
+
o+ +
+
+
Initializes the desired transport.
+Parameters:
+ +-
+
+
-
+
+
o+ Object + + + + +++ + +-
+
- object of transport configurations. +
+
+
transports.nodejs
+
+
+ ()
+
+
+
+
+ Object
+
+
+
+
+
+
+
+
+
+
+ static
+
+
+
+
+
+
+
+
+ NodeJS IO transport, uses the NodeJS request +module under the hood to perform all network IO.
+Returns:
+ +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+ +
+
+
Method for accessing the transport's interface for making a +cross-domain transaction.
+xdrReady
+
+
+ -
+
+
-
+
+
yid+ +
+
+ -
+
+
uid+ +
+
+
Fires event "io:xdrReady"
+xdrResponse
+
+
+ -
+
+
-
+
+
e+ +
+
+ -
+
+
o+ +
+
+ -
+
+
c+ +
+
+
Response controller for cross-domain requests when using the +Flash transport or IE8's XDomainRequest object.
+Parameters:
+ + +Returns:
+ +Properties
+ + +_cB
+ Object
+
+
+
+
+ private
+
+
+
+
+
+
+
+
+ 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
+
+
+
+
+ Array of transactions queued for processing
+_qState
+ Number
+
+
+
+
+ private
+
+
+
+
+
+ static
+
+
+
+
+ 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
+
+
+
+
+
+
+
+
+ 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.
+delay
+ Number
+
+
+
+
+
+
+
+
+ static
+
+
+
+
+ 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
+
+
+
+
+
+
+
+
+
+
+
+
+ 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
+
+
+
+
+
+
+
+
+
+
+
+
+ Fires when the XDR transport is ready for use.
+