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
Methods
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.
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:
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:
An object containing:
id- The transaction ID for this request.
abort- A function to abort the current transaction.
isInProgress- A helper to determine whether the current transaction is in progress.
io- A reference to the IO object for this transaction.
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.
xdrResponse
-
e -
o -
c
Response controller for cross-domain requests when using the Flash transport or IE8's XDomainRequest object.
Parameters:
Returns:
Properties
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.