/**
* Base IO functionality. Provides basic XHR transport support.
* @module io
* @submodule io-base
*/
/**
* 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.
*
* @class io
*/
/**
* @event io:start
* @description This event is fired by YUI.io when a transaction is initiated.
* @type Event Custom
*/
var E_START = 'io:start',
/**
* @event io:complete
* @description This event is fired by YUI.io when a transaction is complete.
* Response status and data are accessible, if available.
* @type Event Custom
*/
E_COMPLETE = 'io:complete',
/**
* @event io:success
* @description This event is fired by YUI.io when a transaction is complete, and
* the HTTP status resolves to HTTP2xx.
* @type Event Custom
*/
E_SUCCESS = 'io:success',
/**
* @event io:failure
* @description This event is fired by YUI.io when a transaction is complete, and
* the HTTP status resolves to HTTP4xx, 5xx and above.
* @type Event Custom
*/
E_FAILURE = 'io:failure',
/**
* @event io:end
* @description This event signifies the end of the transaction lifecycle. The
* transaction transport is destroyed.
* @type Event Custom
*/
E_END = 'io:end',
//--------------------------------------
// Properties
//--------------------------------------
/**
* @description A transaction counter that increments for each transaction.
*
* @property transactionId
* @private
* @static
* @type int
*/
transactionId = 0,
/**
* @description Object of default HTTP headers to be initialized and sent
* for all transactions.
*
* @property _headers
* @private
* @static
* @type object
*/
_headers = {
'X-Requested-With' : 'XMLHttpRequest'
},
/**
* @description Object that stores timeout values for any transaction with
* a defined "timeout" configuration property.
*
* @property _timeout
* @private
* @static
* @type object
*/
_timeout = {},
// Window reference
w = Y.config.win;
//--------------------------------------
// Methods
//--------------------------------------
/**
* @description 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.
* The properties are:
* {
* use: Specify the transport to be used: 'flash' and 'native'
* dataType: Set the value to 'XML' if that is the expected
* response content type.
* }
*
*
* form: This is a defined object used to process HTML form as data. The
* properties are:
* {
* id: Node object or id of HTML form.
* useDisabled: Boolean value to 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, arguments){},
* complete: function(id, responseobject, arguments){},
* success: function(id, responseobject, arguments){},
* failure: function(id, responseobject, arguments){},
* end: function(id, arguments){}
* }
* Each property can reference a function or be written as an
* inline function.
*
* sync: To enable synchronous transactions, set the configuration property
* "sync" to true; the default behavior is false. Synchronous
* transactions are limited to same-domain requests only.
*
* context: Object reference for all defined transaction event handlers
* when it is implemented as a method of a base object. Defining
* "context" will set the reference of "this," used in the
* event handlers, to the context value. In the case where
* different event handlers all have different contexts,
* use Y.bind() to set the execution context, bypassing this
* configuration.
*
* headers: This is a defined object of client headers, as many as.
* desired for the transaction. The 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.
*
* @method _io
* @private
* @static
* @param {string} uri - qualified path to transaction resource.
* @param {object} c - configuration object for the transaction.
* @param {number} i - transaction id, if already set.
* @return object
*/
function _io(uri, c, i) {
var f, o, d, m, r, s, oD,
u = uri;
c = Y.Object(c);
o = _create(c.xdr || c.form, i);
m = c.method ? c.method = c.method.toUpperCase() : c.method = 'GET';
s = c.sync;
oD = c.data;
//To serialize an object into a key-value string, add the
//QueryString module to the YUI instance's 'use' method.
if (Y.Lang.isObject(c.data) && Y.QueryString) {
c.data = Y.QueryString.stringify(c.data);
Y.log('Configuration property "data" is an object. The serialized value is: ' + c.data, 'info', 'io');
}
if (c.form) {
if (c.form.upload) {
return Y.io._upload(o, uri, c);
}
else {
f = Y.io._serialize(c.form, c.data);
if (m === 'POST' || m === 'PUT') {
c.data = f;
}
else if (m === 'GET') {
uri = _concat(uri, f);
}
}
}
else if (c.data && m === 'GET') {
uri = _concat(uri, c.data);
Y.log('HTTP GET with configuration data. The querystring is: ' + uri, 'info', 'io');
}
if (o.t) {
return Y.io.xdr(uri, o, c);
}
if (!s) {
o.c.onreadystatechange = function() { _readyState(o, c); };
}
try {
o.c.open(m, uri, s ? false : true);
// Will work only in browsers that implement the
// Cross-Origin Resource Sharing draft.
if (c.xdr && c.xdr.credentials) {
o.c.withCredentials = true;
}
}
catch(a) {
if (c.xdr) {
// This exception is usually thrown by browsers
// that do not support native XDR transactions.
return _resend(o, u, c, oD);
}
}
if (c.data && m === 'POST') {
c.headers = Y.merge({ 'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8' }, c.headers);
}
_setHeaders(o.c, c.headers);
_ioStart(o.id, c);
try {
// Using "null" with HTTP POST will result in a request
// with no Content-Length header defined.
o.c.send(c.data || '');
if (s) {
d = o.c;
r = c.arguments ? { id: o.id, arguments: c.arguments } : { id: o.id };
r = Y.mix(r, d, false, ['status', 'statusText', 'responseText', 'responseXML']);
r.getAllResponseHeaders = function() { return d.getAllResponseHeaders(); };
r.getResponseHeader = function(h) { return d.getResponseHeader(h); };
_ioComplete(o, c);
_handleResponse(o, c);
return r;
}
}
catch(b) {
if (c.xdr) {
// This exception is usually thrown by browsers
// that do not support native XDR transactions.
return _resend(o, u, c, oD);
}
}
// If config.timeout is defined, and the request is standard XHR,
// initialize timeout polling.
if (c.timeout) {
_startTimeout(o, c.timeout);
Y.log('Configuration timeout set to: ' + c.timeout, 'info', 'io');
}
return {
id: o.id,
abort: function() {
return o.c ? _ioCancel(o, 'abort') : false;
},
isInProgress: function() {
return o.c ? o.c.readyState !== 4 && o.c.readyState !== 0 : false;
}
}
}
/**
* @description Method for creating and subscribing transaction events.
*
* @method _tE
* @private
* @static
* @param {string} e - event to be published
* @param {object} c - configuration data subset for event subscription.
*
* @return void
*/
function _tE(e, c) {
var eT = new Y.EventTarget().publish('transaction:' + e),
a = c.arguments,
cT = c.context || Y;
a ? eT.on(c.on[e], cT, a) : eT.on(c.on[e], cT);
return eT;
}
/**
* @description Fires event "io:start" and creates, fires a
* transaction-specific start event, if config.on.start is
* defined.
*
* @method _ioStart
* @private
* @static
* @param {number} id - transaction id
* @param {object} c - configuration object for the transaction.
*
* @return void
*/
function _ioStart(id, c) {
var a = c.arguments;
// Set default value of argument c, property "on" to Object if
// the property is null or undefined.
c.on = c.on || {};
a ? Y.fire(E_START, id, a) : Y.fire(E_START, id);
if (c.on.start) {
_tE('start', c).fire(id);
}
}
/**
* @description Fires event "io:complete" and creates, fires a
* transaction-specific "complete" event, if config.on.complete is
* defined.
*
* @method _ioComplete
* @private
* @static
* @param {object} o - transaction object.
* @param {object} c - configuration object for the transaction.
*
* @return void
*/
function _ioComplete(o, c) {
var r = o.e ? { status: 0, statusText: o.e } : o.c,
a = c.arguments;
// Set default value of argument c, property "on" to Object if
// the property is null or undefined.
c.on = c.on || {};
a ? Y.fire(E_COMPLETE, o.id, r, a) : Y.fire(E_COMPLETE, o.id, r);
if (c.on.complete) {
_tE('complete', c).fire(o.id, r);
}
}
/**
* @description Fires event "io:success" and creates, fires a
* transaction-specific "success" event, if config.on.success is
* defined.
*
* @method _ioSuccess
* @private
* @static
* @param {object} o - transaction object.
* @param {object} c - configuration object for the transaction.
*
* @return void
*/
function _ioSuccess(o, c) {
var a = c.arguments;
// Set default value of argument c, property "on" to Object if
// the property is null or undefined.
c.on = c.on || {};
a ? Y.fire(E_SUCCESS, o.id, o.c, a) : Y.fire(E_SUCCESS, o.id, o.c);
if (c.on.success) {
_tE('success', c).fire(o.id, o.c);
}
_ioEnd(o, c);
}
/**
* @description Fires event "io:failure" and creates, fires a
* transaction-specific "failure" event, if config.on.failure is
* defined.
*
* @method _ioFailure
* @private
* @static
* @param {object} o - transaction object.
* @param {object} c - configuration object for the transaction.
*
* @return void
*/
function _ioFailure(o, c) {
var r = o.e ? { status: 0, statusText: o.e } : o.c,
a = c.arguments;
// Set default value of argument c, property "on" to Object if
// the property is null or undefined.
c.on = c.on || {};
a ? Y.fire(E_FAILURE, o.id, r, a) : Y.fire(E_FAILURE, o.id, r);
if (c.on.failure) {
_tE('failure', c).fire(o.id, r);
}
_ioEnd(o, c);
}
/**
* @description Fires event "io:end" and creates, fires a
* transaction-specific "end" event, if config.on.end is
* defined.
*
* @method _ioEnd
* @private
* @static
* @param {object} o - transaction object.
* @param {object} c - configuration object for the transaction.
*
* @return void
*/
function _ioEnd(o, c) {
var a = c.arguments;
// Set default value of argument c, property "on" to Object if
// the property is null or undefined.
c.on = c.on || {};
a ? Y.fire(E_END, o.id, a) : Y.fire(E_END, o.id);
if (c.on.end) {
_tE('end', c).fire(o.id);
}
_destroy(o);
}
/**
* @description Terminates a transaction due to an explicit abort or
* timeout.
*
* @method _ioCancel
* @private
* @static
* @param {object} o - Transaction object generated by _create().
* @param {string} s - Identifies timed out or aborted transaction.
*
* @return void
*/
function _ioCancel(o, s) {
if (o && o.c) {
o.e = s;
o.c.abort();
}
}
/**
* @description Resends an XDR transaction, using the Flash tranport,
* if the native transport fails.
*
* @method _resend
* @private
* @static
* @param {object} o - Transaction object generated by _create().
* @param {string} uri - qualified path to transaction resource.
* @param {object} c - configuration object for the transaction.
*
* @return void
*/
function _resend(o, uri, c, d) {
var id = parseInt(o.id);
_destroy(o);
c.xdr.use = 'flash';
// If the original request included serialized form data,
// it must be reset to prevent duplication.
c.form && d ? c.data = d : c.data = null;
return Y.io(uri, c, id);
}
/**
* @description Method that increments _transactionId for each transaction.
*
* @method _id
* @private
* @static
* @return int
*/
function _id() {
var id = transactionId;
transactionId++;
return id;
}
/**
* @description Method that creates a unique transaction object for each
* request.
*
* @method _create
* @private
* @static
* @param {number} c - configuration object subset to determine if
* the transaction is an XDR or file upload,
* requiring an alternate transport.
* @param {number} i - transaction id
* @return object
*/
function _create(c, i) {
var o = {};
o.id = Y.Lang.isNumber(i) ? i : _id();
c = c || {};
if (!c.use && !c.upload) {
o.c = _xhr();
}
else if (c.use) {
if (c.use === 'native') {
if (w.XDomainRequest) {
o.c = new XDomainRequest();
o.t = c.use;
}
else {
o.c = _xhr();
}
}
else {
o.c = Y.io._transport[c.use];
o.t = c.use;
}
// Remove the custom header when making cross-domain
// requests to avoid unintended pre-flight requests
// or access control conflicts.
delete _headers['X-Requested-With'];
}
else {
o.c = {};
}
return o;
};
/**
* @description Method that creates the XMLHttpRequest transport
*
* @method _xhr
* @private
* @static
* @return object
*/
function _xhr() {
return w.XMLHttpRequest ? new XMLHttpRequest() : new ActiveXObject('Microsoft.XMLHTTP');
}
/**
* @description Method that concatenates string data for HTTP GET transactions.
*
* @method _concat
* @private
* @static
* @param {string} s - URI or root data.
* @param {string} d - data to be concatenated onto URI.
* @return int
*/
function _concat(s, d) {
s += ((s.indexOf('?') == -1) ? '?' : '&') + d;
return s;
}
/**
* @description Method that stores default client headers for all transactions.
* If a label is passed with no value argument, the header will be deleted.
*
* @method _setHeader
* @private
* @static
* @param {string} l - HTTP header
* @param {string} v - HTTP header value
* @return int
*/
function _setHeader(l, v) {
if (v) {
_headers[l] = v;
}
else {
delete _headers[l];
}
}
/**
* @description Method that sets all HTTP headers to be sent in a transaction.
*
* @method _setHeaders
* @private
* @static
* @param {object} o - XHR instance for the specific transaction.
* @param {object} h - HTTP headers for the specific transaction, as defined
* in the configuration object passed to YUI.io().
* @return void
*/
function _setHeaders(o, h) {
var p;
h = h || {};
for (p in _headers) {
if (_headers.hasOwnProperty(p)) {
if (h[p]) {
// Configuration headers will supersede io preset headers,
// if headers match.
break;
}
else {
h[p] = _headers[p];
}
}
}
for (p in h) {
if (h.hasOwnProperty(p)) {
o.setRequestHeader(p, h[p]);
}
}
}
/**
* @description Starts timeout count if the configuration object
* has a defined timeout property.
*
* @method _startTimeout
* @private
* @static
* @param {object} o - Transaction object generated by _create().
* @param {object} t - Timeout in milliseconds.
* @return void
*/
function _startTimeout(o, t) {
_timeout[o.id] = w.setTimeout(function() { _ioCancel(o, 'timeout'); }, t);
}
/**
* @description Clears the timeout interval started by _startTimeout().
*
* @method _clearTimeout
* @private
* @static
* @param {number} id - Transaction id.
* @return void
*/
function _clearTimeout(id) {
w.clearTimeout(_timeout[id]);
delete _timeout[id];
}
/**
* @description Event handler bound to onreadystatechange.
*
* @method _readyState
* @private
* @static
* @param {object} o - Transaction object generated by _create().
* @param {object} c - Configuration object passed to YUI.io().
* @return void
*/
function _readyState(o, c) {
if (o.c.readyState === 4) {
if (c.timeout) {
_clearTimeout(o.id);
}
w.setTimeout(
function() {
_ioComplete(o, c);
_handleResponse(o, c);
}, 0);
}
}
/**
* @description 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.
*
* @method _handleResponse
* @private
* @static
* @param {object} o - Transaction object generated by _create().
* @param {object} c - Configuration object passed to io().
* @return void
*/
function _handleResponse(o, c) {
var status;
try{
if (o.c.status && o.c.status !== 0) {
status = o.c.status;
}
else {
status = 0;
}
}
catch(e) {
status = 0;
}
// IE reports HTTP 204 as HTTP 1223.
if (status >= 200 && status < 300 || status === 1223) {
_ioSuccess(o, c);
}
else {
_ioFailure(o, c);
}
}
function _destroy(o) {
// IE, when using XMLHttpRequest as an ActiveX Object, will throw
// a "Type Mismatch" error if the event handler is set to "null".
if (w && w.XMLHttpRequest) {
if (o.c) {
o.c.onreadystatechange = null;
}
}
o.c = null;
o = null;
}
_io.start = _ioStart;
_io.complete = _ioComplete;
_io.success = _ioSuccess;
_io.failure = _ioFailure;
_io.end = _ioEnd;
_io._id = _id;
_io._timeout = _timeout;
//--------------------------------------
// Begin public interface definition
//--------------------------------------
/**
* @description 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().
*
* @method header
* @public
* @static
* @param {string} l - HTTP header
* @param {string} v - HTTP header value
* @return int
*/
_io.header = _setHeader;
/**
* @description Method for requesting a transaction. This
* is the interface for _io().
*
* @method io
* @public
* @static
* @param {string} uri - qualified path to transaction resource.
* @param {object} c - configuration object for the transaction.
* @return object
*/
Y.io = _io;
Y.io.http = _io;