YUI 3: IO
YUI io is a communication utility that enables HTTP requests while maintaining a persistent client UI, for the purpose of data retrieval and content update. It uses the XMLHttpRequest object for making "same-domain" requests, and it can make cross-domain requests, when instructed to do so, using alternate transports.
More Information
- Examples: IO Utility in action.
- API Documentation: View the full API documentation for the IO Utility.
- Download: IO Utility as part of the full YUI Library.
- Free Hosting on our fast edge servers with combo-loading.
- License: BSD.
Getting Started
Include Dependencies
The easiest way to include the source files for IO and its dependencies is to add the YUI seed file to your page, using the following script tag, and allow the YUI instance to download any additional files which may be required:
<script src="http://yui.yahooapis.com/3.0.0/build/yui/yui-min.js"></script>
<script src="http://yui.yahooapis.com/3.0.0/build/yui/yui-min.js"></script>The YUI instance will automatically pull down IO's source files and any missing dependencies when the io module is used. This helps you avoid having to manually manage the list of files needed on your page to support multiple components while also optimizing your initial page weight by loading files only when they are required.
If you do want to include file dependencies manually on your page, the YUI Dependency Configurator can be used to determine the list of files you need to include in order to use IO.
The YUI Instance
Once you have the YUI seed file on your page (yui-min.js), you can
create a new YUI instance for your application to use and populate it
with the modules you need, specified as the first set of arguments to the
use method:
// Create new YUI instance, and populate it with the required modules YUI().use('io', function(Y) { // IO available, and ready for use. });
// Create new YUI instance, and populate it with the required modules YUI().use('io', function(Y) { // IO available, and ready for use. });
The last argument passed to use is a callback function. The callback function will be invoked as soon as the YUI instance is done downloading any required files missing from your page. Once those files are loaded, your local YUI instance will be supplemented with the classes which make up the io module and any modules it depends on. A reference to the populated YUI instance (Y) is passed back to your callback function. Within your callback, then, you can start writing your application code based on your own custom instance of YUI.
For more information on creating instances of YUI and the
use method, see the
YUI Global object documentation.
A Simple Transaction
io() is the primary method for making an HTTP request. This method accepts two arguments: uri and the configuration object.
- uri: This parameter specifies the URI for the transaction
- configuration: This parameter is an object of keys and values of configurations specific to the transaction. Please see: The Configuration Object for more information on all available configuration properties.
YUI.io returns an object with the following members:
- id: This is the unique identifier of the transaction.
- abort(): Aborts the specific transaction.
- isInProgress(): Returns a boolean value indicating whether the transaction has completed.
This is an example GET transaction, handling the response at the earliest opportunity.
// Create a YUI instance using io-base module. YUI().use("io-base", function(Y) { var uri = "get.php?foo=bar"; // Define a function to handle the response data. function complete(id, o, args) { var id = id; // Transaction ID. var data = o.responseText; // Response data. var args = args[1]; // 'ipsum'. }; // Subscribe to event "io:complete", and pass an array // as an argument to the event handler "complete", since // "complete" is global. At this point in the transaction // lifecycle, success or failure is not yet known. Y.on('io:complete', complete, this, ['lorem', 'ipsum']); // Make an HTTP request to 'get.php'. // NOTE: This transaction does not use a configuration object. var request = Y.io(uri); });
// Create a YUI instance using io-base module. YUI().use("io-base", function(Y) { var uri = "get.php?foo=bar"; // Define a function to handle the response data. function complete(id, o, args) { var id = id; // Transaction ID. var data = o.responseText; // Response data. var args = args[1]; // 'ipsum'. }; // Subscribe to event "io:complete", and pass an array // as an argument to the event handler "complete", since // "complete" is global. At this point in the transaction // lifecycle, success or failure is not yet known. Y.on('io:complete', complete, this, ['lorem', 'ipsum']); // Make an HTTP request to 'get.php'. // NOTE: This transaction does not use a configuration object. var request = Y.io(uri); });
Using io
This section describes how to use the IO Utility in further detail. It contains these subsections:
- Modules
- The Configuration Object
- Events
- Cross-Domain Requests
- Serializing HTML Forms as Data
- Uploading files in an HTML Form
- Setting HTTP Headers
- Queue
The io modules
Beginning with PR2, io's core and supplementary features are split into a base module and sub-modules, to allow greater flexibility in selecting the desired features.
| Module | Description |
|---|---|
io-base |
This is the io base class, containing the basic functionality needed for making HTTP requests. |
io-xdr |
This sub-module extends io-base, to add cross-domain request capabilities using alternate HTTP transports. |
io-form |
This sub-module extends io-base, to add the ability to serialize HTML form data for POST transactions. |
io-upload-iframe |
This sub-module extends io-base, to allow file uploads with an HTML form, using an iframe as the transaction transport. |
io-queue |
This sub-module extends io-base, to provide a basic queue interface for io. |
The Configuration Object
This object is the second argument of io(). Its properties define transaction parameters and transaction response handling. The configuration object and all configuration properties are optional. The following table describes all configuration properties used by io.
| Property | Description |
|---|---|
| method (string) | Defines the HTTP method for the transaction. If this property is undefined or omitted, the default value is GET. |
| data (string) | Data to be sent with HTTP GET and POST transactions. Data are sent as a string of key-value pairs (e.g., "foo=bar&baz=boo"). |
| headers (object) | Specific HTTP headers and values to be sent with the transaction (e.g., { 'Content-Type': 'application/xml; charset=utf-8' } ). |
| on (object) | This object defines the events and event handlers to be used for the transaction. These events fire in addition to the global io events. Define as many events as desired for the transaction; all events handlers are optional.
|
| context | Defines the execution context of the event handler functions for the transaction. If undefined, a default value of window is used. |
| form (object) | This object instructs io to use the labels and values of the specified HTML form as data.
|
| xdr (object) | Defines the transport to be used for cross-domain requests (e.g., { use:'flash' } ). The transaction will use the specified transport instead of XMLHttpRequest, when specified in the transaction's configuration object.
|
| arguments (object) | Object, array, string, or number passed to all registered, transaction event handlers. This value is available as the second argument in the "start" and "end" event handlers; and, it is the third argument in the "complete", "success", and "failure" event handlers. |
| timeout | This value, defined as milliseconds, is a time threshold for the transaction (e.g., { timeout: 2000 } ). When this limit is reached, and the transaction's Complete event has not yet fired, the transaction will be aborted. |
This is an example of a configuration object, with a set of properties defined.
/* * This is an example configuration object with all properties defined. * * method: This transaction will use HTTP POST. * data: "user=yahoo" is the POST data. * headers: Object of HTTP request headers for this transaction. The * first header defines "Content-Type" and the second is a * custom header. * on: Object of defined event handlers for "start", "complete", * and "end". These handlers are methods of an object * named "Dispatch". * context: Event handlers will execute in the propert object context, * so usage 'this' will reference Dispatch. * form: Object specifying the HTML form to be serialized into a key-value * string and sent as data; and, informing io to include disabled * HTML form fields as part of the data. If input type of "file" * is present, setting the upload property to "true" will create an * alternate transport, to submit the HTML form with the * selected files. * xdr: Instructs io to use the defined transport, in this case Flash, * to make a cross-domain request for this transaction. * arguments: Object of data, passed as an argument to the event * handlers. */ var cfg = { method: 'POST', data: 'user=yahoo', headers: { 'Content-Type': 'application/json', 'X-TRANSPORT-TYPE': 'Flash' }, on: { start: Dispatch.start, complete: Dispatch.complete, end: Dispatch.end } }, context: Dispatch, form: { id: formObject, useDisabled: true, upload: true }, xdr: { use: 'flash', dataType: 'xml' }, arguments: { start: 'foo', complete: 'bar', end: 'baz' } };
/* * This is an example configuration object with all properties defined. * * method: This transaction will use HTTP POST. * data: "user=yahoo" is the POST data. * headers: Object of HTTP request headers for this transaction. The * first header defines "Content-Type" and the second is a * custom header. * on: Object of defined event handlers for "start", "complete", * and "end". These handlers are methods of an object * named "Dispatch". * context: Event handlers will execute in the propert object context, * so usage 'this' will reference Dispatch. * form: Object specifying the HTML form to be serialized into a key-value * string and sent as data; and, informing io to include disabled * HTML form fields as part of the data. If input type of "file" * is present, setting the upload property to "true" will create an * alternate transport, to submit the HTML form with the * selected files. * xdr: Instructs io to use the defined transport, in this case Flash, * to make a cross-domain request for this transaction. * arguments: Object of data, passed as an argument to the event * handlers. */ var cfg = { method: 'POST', data: 'user=yahoo', headers: { 'Content-Type': 'application/json', 'X-TRANSPORT-TYPE': 'Flash' }, on: { start: Dispatch.start, complete: Dispatch.complete, end: Dispatch.end } }, context: Dispatch, form: { id: formObject, useDisabled: true, upload: true }, xdr: { use: 'flash', dataType: 'xml' }, arguments: { start: 'foo', complete: 'bar', end: 'baz' } };
The Response Object
When a transaction, using the XHR object as a transport, is complete, the response data are passed as an object to the event handler.
| Field | Description |
|---|---|
| status | The HTTP status code of the transaction. |
| statusText | The HTTP status message. |
| getResponseHeader(headername) | Returns the string value of the specified header label. |
| getAllResponseHeaders | All response HTTP headers are available as a string. Each key-value pair is delimited by "\n". |
| responseText | The response data as a decoded string. |
| responseXML | The response data as an XML document. |
NOTE: Transactions involving file upload or cross-domain requests, using alternate transports, only populate the responseText or responseXML field. The HTTP status and response headers are either inaccessible or unavailable to these alternate transports.
Events
YUI io events provide access to state and data during a transaction's lifecycle. There are two aspects to io events: global and transaction. Global events are always fired by io for all transactions, and these events are accessible to all event subscribers. Transaction events are created and fired only if they are defined in the configuration object. Global events are identified by the io:eventname pattern. The following example describes the event subscription syntax for global events:
The following table describes the available io events:
| Event | Description |
|---|---|
| io:start |
Fires when a request is made to a resource. The event handler's arguments signature is:
function onStart(transactionid, arguments) { // transactionid : The transaction's ID. // arguments: Array ['foo','bar']. } // Subscribe to "io.start". Y.on('io:start', onStart, this, { start: ['foo','bar']; ); |
| io:complete |
Fires after "io:start", when the transaction is complete and response data are available. This is the earliest opportunity to access any response data. The event handler's arguments signature is:
function onComplete(transactionid, response, arguments) { // transactionid : The transaction's ID. // response: The response object. // arguments: Object containing an array { complete: ['foo', 'bar'] }. } // Subscribe to "io.complete". Y.on('io:complete', onComplete, this, { complete: ['foo', 'bar'] } ); |
| io:success |
Fires after the "complete" event, when the response HTTP status resolves to 2xx. The event handler's arguments signature is:
function onSuccess(transactionid, response, arguments) { // transactionid : The transaction's ID. // response: The response object. // arguments: Boolean value "true". } // Subscribe to "io.success". Y.on('io:success', onSuccess, this, true); |
| io:failure |
Fires after the "complete" event, when the response HTTP status resolves to 4xx. 5xx, undefined, or a non-standard HTTP status. This event also includes 'abort' and 'timeout' conditions. The event handler's arguments signature is:
function onFailure(transactionid, response, arguments) { // transactionid : The transaction's ID. // response: The response object. Only status and statusText // are populated when the transaction is terminated // due to abort or timeout. The status will read // 0, and statusText will return "timeout" or "abort" // depending on the mode of termination. // arguments: String "Transaction Failed". } // Subscribe to "io.failure". Y.on('io:failure', onFailure, this, 'Transaction Failed'); |
| io:end |
Fires at the conclusion of a transaction, after "success" or "failure" has been determined.. The event handler's arguments signature is:
function onEnd(transactionid, arguments) { // transactionid : The transaction's ID. // arguments: Number 0. } // Subscribe to "io.end". Y.on('io:end', onEnd, this, 0); |
| io:xdrReady | Fires when the flash XDR transport is ready for use. This event only fires once, when the transport initialization is complete. |
The following example demonstrates an io transaction with an event handler subscribed to "io:complete".
// Create a YUI instance using io module. YUI().use("io-base", function(Y) { /* * Create a function as the event handler for the event "io:complete". * * The function will receive the following arguments: * - The ID of the transaction * - Object containing the response data. * - Argument one defined when subscribing to the event(e.g., "foo"). * - Argument two defined when subscribing to the event(e.g., "bar"). */ function onComplete(transactionId, responseObject, arg1, arg2) { /* * The argument 'responseObject' is the response object. Its * properties are: * - status * - statusText * - getResponseHeader(headerName) * - getAllResponseHeaders * - responseText * - responseXML * * NOTE: In an XDR transaction, only the responseText or the responseXML property is defined. */ }; /* * Subscribe to the event "io:complete", using Y.on. * * - 'io:complete' : Subscribe to this io event. * - onComplete : The event handler to be subscribed to 'io:complete'. * - Y : The execution context of the event handler, in this case, the YUI sandbox. * since the doComplete is defined as a global function. * - 'foo' : The first argument received by the event handler. * - 'bar' : The second argument received by the event handler. * Additional arguments can be defined, as desired. */ Y.on('io:complete', onComplete, this, "foo", "bar"); // Starts the transaction. var request = Y.io(uri); });
// Create a YUI instance using io module. YUI().use("io-base", function(Y) { /* * Create a function as the event handler for the event "io:complete". * * The function will receive the following arguments: * - The ID of the transaction * - Object containing the response data. * - Argument one defined when subscribing to the event(e.g., "foo"). * - Argument two defined when subscribing to the event(e.g., "bar"). */ function onComplete(transactionId, responseObject, arg1, arg2) { /* * The argument 'responseObject' is the response object. Its * properties are: * - status * - statusText * - getResponseHeader(headerName) * - getAllResponseHeaders * - responseText * - responseXML * * NOTE: In an XDR transaction, only the responseText or the responseXML property is defined. */ }; /* * Subscribe to the event "io:complete", using Y.on. * * - 'io:complete' : Subscribe to this io event. * - onComplete : The event handler to be subscribed to 'io:complete'. * - Y : The execution context of the event handler, in this case, the YUI sandbox. * since the doComplete is defined as a global function. * - 'foo' : The first argument received by the event handler. * - 'bar' : The second argument received by the event handler. * Additional arguments can be defined, as desired. */ Y.on('io:complete', onComplete, this, "foo", "bar"); // Starts the transaction. var request = Y.io(uri); });
Cross-Domain Transactions
By default, io uses the XMLHttpRequest object as the transport for HTTP transactions. It can also be configured to use an alternate transport to make cross-domain, HTTP transactions. Currently, io can make use of Flash as one of two alternate transports. To prepare io for Flash-based, cross-domain transactions, the transport io.swf must be deployed and accessible to YUI io. For each transaction, the configuration object's xdr object must be defined as { use: 'flash' } so io will use the designated transport (instead of using the default transport of XMLHttpRequest).
As io.swf is written in ActionScript 3, Flash Player 9 or better is required (version 9.0.124 or better is recommended). Additionally, a cross-domain policy file must be deployed at the resource to grant the client access to the remote domain. A cross-domain request will not be successful without this policy file hosted at the resource. The following example file grants permissive access to the host from all requests, but the host will only accept custom HTTP headers originating from yahoo.com.
<?xml version="1.0"?> <!DOCTYPE cross-domain-policy SYSTEM "http://www.adobe.com/xml/dtds/cross-domain-policy.dtd"> <cross-domain-policy> <allow-access-from domain="*"/> <allow-http-request-headers-from domain="*.yahoo.com" headers="*"/> </cross-domain-policy>
<?xml version="1.0"?> <!DOCTYPE cross-domain-policy SYSTEM "http://www.adobe.com/xml/dtds/cross-domain-policy.dtd"> <cross-domain-policy> <allow-access-from domain="*"/> <allow-http-request-headers-from domain="*.yahoo.com" headers="*"/> </cross-domain-policy>
For more information on cross-domain policy file specifications, see the following articles at Adobe Developer Connection.
The following example demonstrates a cross-domain transaction, starting with the initialization of the XDR transport and subscribing to three global io events.
// Create a YUI instance using the io cross-domain submodule YUI().use("io-xdr", function(Y) { // Create a configuration object with the src property defined, // src: The path to the Flash file, relative to the HTML. var xdrCfg = { src:'io.swf' }; // Initialize the define transport Y.io.transport(xdrCfg); // Define the configurations to be used for each transaciton.. var cfg = { use: 'flash', // Instruct io to use the flash XDR transport. data: 'foo=bar&baz=boo' // Key-value string of data. timeout: 3000, // Abort the transaction, if it is still pending, after 3000ms. // An object passed, as an argument, to the event handlers. arguments: { start: 'foo', complete: 'bar', end: 'baz' } }; /* * GlobalEventHandler is an example object that encapsulates * event handlers for "io:start", "io:complete", and "io:end". * * start( ) // Event handler for "io:start" * success( ) // Event handler for "io:complete". * end( ) // Event handler for "io:end". */ var GlobalEventHandler = { start: function(id, args) { var args = args.start // 'foo' }, success: function(id, o, args) { var args = args.complete; // 'bar' var data = o.responseText; var xml = o.responseXML; }, end: function(id, args) { var args = args.end // args = 'baz' } }; // Subscribe GlobalEventHandler.start to event "io:start". Y.on('io:start', GlobalEventHandler.start, this); // Subscribe GlobalEventHandler.complete to event "io:complete". Y.on('io:success', GlobalEventHandler.complete, this); // Subscribe GlobalEventHandler to event "io:end". Y.on('io:end', GlobalEventHandler.end, this); // Start the transaction var request = Y.io(uri, cfg); });
// Create a YUI instance using the io cross-domain submodule YUI().use("io-xdr", function(Y) { // Create a configuration object with the src property defined, // src: The path to the Flash file, relative to the HTML. var xdrCfg = { src:'io.swf' }; // Initialize the define transport Y.io.transport(xdrCfg); // Define the configurations to be used for each transaciton.. var cfg = { use: 'flash', // Instruct io to use the flash XDR transport. data: 'foo=bar&baz=boo' // Key-value string of data. timeout: 3000, // Abort the transaction, if it is still pending, after 3000ms. // An object passed, as an argument, to the event handlers. arguments: { start: 'foo', complete: 'bar', end: 'baz' } }; /* * GlobalEventHandler is an example object that encapsulates * event handlers for "io:start", "io:complete", and "io:end". * * start( ) // Event handler for "io:start" * success( ) // Event handler for "io:complete". * end( ) // Event handler for "io:end". */ var GlobalEventHandler = { start: function(id, args) { var args = args.start // 'foo' }, success: function(id, o, args) { var args = args.complete; // 'bar' var data = o.responseText; var xml = o.responseXML; }, end: function(id, args) { var args = args.end // args = 'baz' } }; // Subscribe GlobalEventHandler.start to event "io:start". Y.on('io:start', GlobalEventHandler.start, this); // Subscribe GlobalEventHandler.complete to event "io:complete". Y.on('io:success', GlobalEventHandler.complete, this); // Subscribe GlobalEventHandler to event "io:end". Y.on('io:end', GlobalEventHandler.end, this); // Start the transaction var request = Y.io(uri, cfg); });
Note: XDR transactions do not fire the global io:complete event and the transaction-specific complete event, when using the Flash transport. All other events in the transaction lifecycle are fired.
A subset of A-grade browsers are capable of making cross-domain requests, using XMLHttpRequest, requiring specific access control headers be served from the resource. To use this feature, the xdr object must be defined with: { use: 'native' }. YUI io will try to resolve the request using the native transport, and it will fall back to the Flash transport if the initial attempt throws an exception due to the browser lacking native support.
NOTE: For native cross-domain requests to work, the resource must respond with the "Access-Control-Allow-Origin" header with a value permitting the client to make the request. In the absence of these HTTP response headers, the transaction will always fail. Please see the following articles for more information on this topic.
- Mozilla Developer Center: HTTP Access Control article.
- MSDN: Cross-Domain Security article.
- W3C: Access Control Working Draft,
Serializing HTML Form as Data
YUI io can serialize HTML form fields into a string of UTF-8 encoded, name-value pairs. If the transaction is HTTP GET, the data are appended to the URI as a querystring. If the transaction if HTTP POST, the data will be the POST message.
// Create a YUI instance using the io-form sub-module. YUI().use("io-form", function(Y) { // Create a configuration object for the file upload transaction. // The form configuration should include two defined properties: // id: This can be the ID or an object reference to the HTML form. // useDisabled: Set this property to "true" to include disabled // HTML form fields, as part of the data. By // default, disabled fields are excluded from the // serialization. // The HTML form data are sent as a UTF-8 encoded key-value string. var cfg = { method: 'POST', form: { id: formObject, useDisabled: true } }; // Define a function to handle the response data. function complete(id, o, args) { var id = id; // Transaction ID. var data = o.responseText; // Response data. var args = args[1]; // 'ipsum'. }; // Subscribe to event "io:complete", and pass an array // as an argument to the event handler "complete". Y.on('io:complete', complete, this, { 'foo':'bar' }); // Start the transaction. var request = Y.io(uri, cfg); });
// Create a YUI instance using the io-form sub-module. YUI().use("io-form", function(Y) { // Create a configuration object for the file upload transaction. // The form configuration should include two defined properties: // id: This can be the ID or an object reference to the HTML form. // useDisabled: Set this property to "true" to include disabled // HTML form fields, as part of the data. By // default, disabled fields are excluded from the // serialization. // The HTML form data are sent as a UTF-8 encoded key-value string. var cfg = { method: 'POST', form: { id: formObject, useDisabled: true } }; // Define a function to handle the response data. function complete(id, o, args) { var id = id; // Transaction ID. var data = o.responseText; // Response data. var args = args[1]; // 'ipsum'. }; // Subscribe to event "io:complete", and pass an array // as an argument to the event handler "complete". Y.on('io:complete', complete, this, { 'foo':'bar' }); // Start the transaction. var request = Y.io(uri, cfg); });
Uploading Files in an HTML Form
The default XHR transport, used in io, cannot upload HTML form data that include elements of type="file". In this situation, io will use an alternate transport -- an iframe -- to facilitate the transaction. The following example shows how to configure a transaction involving file upload:
/* * This example demonstrates how to configure io to upload files * from an HTML form. This example uses the global events: * "io:start" and "io:complete" to handle the transaction and * response. Transaction events can be defined and fired, as well, * in the configuration object; but, they are not used in this * example. */ // Create a YUI instance using the io-upload-iframe sub-module. YUI().use("io-upload-iframe", function(Y) { // Create a configuration object for the file upload transaction. // The form configuration should include two defined properties: // id: This can be the ID or an object reference to the HTML form // containing the input type="file" elements. // upload: Set this property to "true" to indicate this is a file // upload transaction. var cfg = { method: 'POST', form: { id: formObject, upload: true } }; // Define a function to handle the start of a transaction function start(id, args) { var id = id; // Transaction ID. var args = args.foo; // 'bar' } // Define a function to handle the response data. function complete(id, o, args) { var id = id; // Transaction ID. var data = o.responseText; // Response data. var args = args[1]; // 'ipsum'. }; // Subscribe to event "io:start", and pass an object // as an argument to the event handler "start". Y.on('io:start', start, Y, { 'foo':'bar' }); // Subscribe to event "io:complete", and pass an array // as an argument to the event handler "complete". Y.on('io:complete', complete, Y, ['lorem', 'ipsum']); // Start the transaction. var request = Y.io(uri, cfg); });
/* * This example demonstrates how to configure io to upload files * from an HTML form. This example uses the global events: * "io:start" and "io:complete" to handle the transaction and * response. Transaction events can be defined and fired, as well, * in the configuration object; but, they are not used in this * example. */ // Create a YUI instance using the io-upload-iframe sub-module. YUI().use("io-upload-iframe", function(Y) { // Create a configuration object for the file upload transaction. // The form configuration should include two defined properties: // id: This can be the ID or an object reference to the HTML form // containing the input type="file" elements. // upload: Set this property to "true" to indicate this is a file // upload transaction. var cfg = { method: 'POST', form: { id: formObject, upload: true } }; // Define a function to handle the start of a transaction function start(id, args) { var id = id; // Transaction ID. var args = args.foo; // 'bar' } // Define a function to handle the response data. function complete(id, o, args) { var id = id; // Transaction ID. var data = o.responseText; // Response data. var args = args[1]; // 'ipsum'. }; // Subscribe to event "io:start", and pass an object // as an argument to the event handler "start". Y.on('io:start', start, Y, { 'foo':'bar' }); // Subscribe to event "io:complete", and pass an array // as an argument to the event handler "complete". Y.on('io:complete', complete, Y, ['lorem', 'ipsum']); // Start the transaction. var request = Y.io(uri, cfg); });
When performing file upload transactions, a subset of global and transaction events will be fired. Specifically, these are:
- Start
- Complete
- End
Success and Failure events are not processed and fired because the iframe transport does not provide access to the HTTP status and response headers, to reliably determine those conditions.
Setting HTTP Headers
The io utility can be configure to send default, custom HTTP Headers for all transactions, in addition to any headers defined in the configuration object. Headers can be set or removed as needed. The following example shows how to set and how to delete default headers in io:
YUI().use("io-base", function(Y) { // Set a new default HTTP header. Y.io.header('Content-Type', 'application/json'); // To remove an existing header, use the same method, but omit the value. Y.io.header('Content-Type'); });
YUI().use("io-base", function(Y) { // Set a new default HTTP header. Y.io.header('Content-Type', 'application/json'); // To remove an existing header, use the same method, but omit the value. Y.io.header('Content-Type'); });
Custom HTTP headers may or may not be sent in cross domain requests. This is may be due to limitations of the transport, or specific "Access-Control" headers requirement.
Queue
YUI io's queue implements YUI Queue to provide sychronous, transaction response. Specifically, transactions are handled -- by global or transaction event handlers -- in the order they are sent, regardless of actual server response order. Transactions can be promoted to the front of the queue, or they can be purged from the queue, as well.
| Field | Description |
|---|---|
| queue(uri, configuration) | Method signature is identical to io, but returns the id of the transaction. |
| queue.start() | Activates the queue, and begins processing transactions in the queue. This is the default state of the queue. |
| queue.stop() | Deactivates the queue. Transactions sent to queue() will be stored until the queue is re-started. | queue.promote(id) | Moves the specified transaction stored in the queue to the head of the queue. |
| queue.remove(id) | Deletes the specified transaction stored in the queue. |
// Create a YUI instance using the io queue sub-module. YUI().use("io-queue", function(Y) { // Stop the queue so transactions can be stored. Y.io.queue.stop(); // Send four transactions into the queue for storage. var task0 = Y.io.queue(uri); var task1 = Y.io.queue(uri); var task2 = Y.io.queue(uri); var task3 = Y.io.queue(uri); // Promote task2 to the top of the queue. Y.io.queue.promote(task2); // Purge task3 from the queue. Y.io.queue.purge(task3); // Re-start the queue. // Transactions are sent in the following order: task2, task0, task 1. // Transaction callbacks, if provided, will be processed in the same // sequence: task2, task0, task1, regardless of actual response order. // Y.io.queue.start(); });
// Create a YUI instance using the io queue sub-module. YUI().use("io-queue", function(Y) { // Stop the queue so transactions can be stored. Y.io.queue.stop(); // Send four transactions into the queue for storage. var task0 = Y.io.queue(uri); var task1 = Y.io.queue(uri); var task2 = Y.io.queue(uri); var task3 = Y.io.queue(uri); // Promote task2 to the top of the queue. Y.io.queue.promote(task2); // Purge task3 from the queue. Y.io.queue.purge(task3); // Re-start the queue. // Transactions are sent in the following order: task2, task0, task 1. // Transaction callbacks, if provided, will be processed in the same // sequence: task2, task0, task1, regardless of actual response order. // Y.io.queue.start(); });
Known Issues
- IE will fail to fire the event
io:xdrReadyif the page is manually reloaded. A timestamp querystring is added to io.swf, in the XDR example, to correct this condition. - Multiple HTML Submit buttons, in an HTML form, are not supported.
Support & Community
Forums & Blog
YUI 3 discussion forums are hosted on YUILibrary.com.
In addition, please visit the YUIBlog for updates and articles about the YUI Library written by the library's developers.
Filing Bugs & Feature Requests
The YUI Library's public bug tracking and feature request repositories are located on the YUILibrary.com site. Before filing new feature requests or bug reports, please review our reporting guidelines.

