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:
-
configObjectObject of EventTarget's publish method configurations used to configure IO's events.
Item Index
Methods
- _abort
- _abort
- _addData static
- _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
- 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
Methods
_abort
-
o -
c
Method for intiating an XDR transaction abort.
_abort
-
transaction -
type
Terminates a transaction due to an explicit abort or timeout.
_addData
-
f -
s
Parses the POST data object and creates hidden form elements for each key-value, and appends them to the HTML form object.
Returns:
o Array of created fields.
_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:
-
idNumber- Transaction id.
_clearUploadTimeout
-
id
Clears the timeout interval started by _startUploadTimeout().
Parameters:
-
idNumber- Transaction ID.
_concat
-
uri -
data
Method that concatenates string data for HTTP GET transactions.
Returns:
_create
-
cfg -
id
Method that creates a unique transaction object for each request.
Parameters:
Returns:
The transaction object
_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:
-
idNumberThe 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:
-
oObject- 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.
_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 -
uid
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"
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:
-
oObjectThe headers object
Returns:
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.
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.
<p>Callback functions forstartandendreceive the id of the transaction as a first argument. Forcomplete,success, andfailure, callbacks receive the id and the response object (usually the XMLHttpRequest instance). If theargumentsproperty was included in the configuration object passed toY.io(), the configured data will be passed to all callbacks as the last argument.</p> </dd> - 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 usingY.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.
- username
- Username to use in a HTTP authentication.
- password
- Password to use in a HTTP authentication.
- 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:
-
oObject- 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:
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
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.
_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 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
Fires when the XDR transport is ready for use.