/**
* Provides a mechanism to fetch remote resources and
* insert them into a document.
* @module yui
* @submodule get
*/
var ua = Y.UA,
L = Y.Lang,
TYPE_JS = 'text/javascript',
TYPE_CSS = 'text/css',
STYLESHEET = 'stylesheet';
/**
* Fetches and inserts one or more script or link nodes into the document
* @class Get
* @static
*/
Y.Get = function() {
/**
* hash of queues to manage multiple requests
* @property queues
* @private
*/
var _get, _purge, _track,
queues = {},
/**
* queue index used to generate transaction ids
* @property qidx
* @type int
* @private
*/
qidx = 0,
/**
* interal property used to prevent multiple simultaneous purge
* processes
* @property purging
* @type boolean
* @private
*/
purging,
/**
* Generates an HTML element, this is not appended to a document
* @method _node
* @param {string} type the type of element.
* @param {string} attr the attributes.
* @param {Window} win optional window to create the element in.
* @return {HTMLElement} the generated node.
* @private
*/
_node = function(type, attr, win) {
var w = win || Y.config.win,
d = w.document,
n = d.createElement(type),
i;
for (i in attr) {
if (attr[i] && attr.hasOwnProperty(i)) {
n.setAttribute(i, attr[i]);
}
}
return n;
},
/**
* Generates a link node
* @method _linkNode
* @param {string} url the url for the css file.
* @param {Window} win optional window to create the node in.
* @param {object} attributes optional attributes collection to apply to the
* new node.
* @return {HTMLElement} the generated node.
* @private
*/
_linkNode = function(url, win, attributes) {
var o = {
id: Y.guid(),
type: TYPE_CSS,
rel: STYLESHEET,
href: url
};
if (attributes) {
Y.mix(o, attributes);
}
return _node('link', o, win);
},
/**
* Generates a script node
* @method _scriptNode
* @param {string} url the url for the script file.
* @param {Window} win optional window to create the node in.
* @param {object} attributes optional attributes collection to apply to the
* new node.
* @return {HTMLElement} the generated node.
* @private
*/
_scriptNode = function(url, win, attributes) {
var o = {
id: Y.guid(),
type: TYPE_JS
};
if (attributes) {
Y.mix(o, attributes);
}
o.src = url;
return _node('script', o, win);
},
/**
* Returns the data payload for callback functions.
* @method _returnData
* @param {object} q the queue.
* @param {string} msg the result message.
* @param {string} result the status message from the request.
* @return {object} the state data from the request.
* @private
*/
_returnData = function(q, msg, result) {
return {
tId: q.tId,
win: q.win,
data: q.data,
nodes: q.nodes,
msg: msg,
statusText: result,
purge: function() {
_purge(this.tId);
}
};
},
/**
* The transaction is finished
* @method _end
* @param {string} id the id of the request.
* @param {string} msg the result message.
* @param {string} result the status message from the request.
* @private
*/
_end = function(id, msg, result) {
var q = queues[id], sc;
if (q && q.onEnd) {
sc = q.context || q;
q.onEnd.call(sc, _returnData(q, msg, result));
}
},
/*
* The request failed, execute fail handler with whatever
* was accomplished. There isn't a failure case at the
* moment unless you count aborted transactions
* @method _fail
* @param {string} id the id of the request
* @private
*/
_fail = function(id, msg) {
Y.log('get failure: ' + msg, 'warn', 'get');
var q = queues[id], sc;
if (q.timer) {
// q.timer.cancel();
clearTimeout(q.timer);
}
// execute failure callback
if (q.onFailure) {
sc = q.context || q;
q.onFailure.call(sc, _returnData(q, msg));
}
_end(id, msg, 'failure');
},
/**
* The request is complete, so executing the requester's callback
* @method _finish
* @param {string} id the id of the request.
* @private
*/
_finish = function(id) {
// Y.log("Finishing transaction " + id, "info", "get");
var q = queues[id], msg, sc;
if (q.timer) {
// q.timer.cancel();
clearTimeout(q.timer);
}
q.finished = true;
if (q.aborted) {
msg = 'transaction ' + id + ' was aborted';
_fail(id, msg);
return;
}
// execute success callback
if (q.onSuccess) {
sc = q.context || q;
q.onSuccess.call(sc, _returnData(q));
}
_end(id, msg, 'OK');
},
/**
* Timeout detected
* @method _timeout
* @param {string} id the id of the request.
* @private
*/
_timeout = function(id) {
Y.log('Timeout ' + id, 'info', 'get');
var q = queues[id], sc;
if (q.onTimeout) {
sc = q.context || q;
q.onTimeout.call(sc, _returnData(q));
}
_end(id, 'timeout', 'timeout');
},
/**
* Loads the next item for a given request
* @method _next
* @param {string} id the id of the request.
* @param {string} loaded the url that was just loaded, if any.
* @return {string} the result.
* @private
*/
_next = function(id, loaded) {
// Y.log("_next: " + id + ", loaded: " + (loaded || "nothing"), "info", "get");
var q = queues[id], msg, w, d, h, n, url, s,
insertBefore;
if (q.timer) {
// Y.log('cancel timer');
// q.timer.cancel();
clearTimeout(q.timer);
}
if (q.aborted) {
msg = 'transaction ' + id + ' was aborted';
_fail(id, msg);
return;
}
if (loaded) {
q.url.shift();
if (q.varName) {
q.varName.shift();
}
} else {
// This is the first pass: make sure the url is an array
q.url = (L.isString(q.url)) ? [q.url] : q.url;
if (q.varName) {
q.varName = (L.isString(q.varName)) ? [q.varName] : q.varName;
}
}
w = q.win;
d = w.document;
h = d.getElementsByTagName('head')[0];
if (q.url.length === 0) {
_finish(id);
return;
}
url = q.url[0];
// if the url is undefined, this is probably a trailing comma
// problem in IE.
if (!url) {
q.url.shift();
Y.log('skipping empty url');
return _next(id);
}
Y.log('attempting to load ' + url, 'info', 'get');
if (q.timeout) {
// Y.log('create timer');
// q.timer = L.later(q.timeout, q, _timeout, id);
q.timer = setTimeout(function() {
_timeout(id);
}, q.timeout);
}
if (q.type === 'script') {
n = _scriptNode(url, w, q.attributes);
} else {
n = _linkNode(url, w, q.attributes);
}
// track this node's load progress
_track(q.type, n, id, url, w, q.url.length);
// add the node to the queue so we can return it to the user supplied
// callback
q.nodes.push(n);
// add it to the head or insert it before 'insertBefore'. Work around
// IE bug if there is a base tag.
insertBefore = q.insertBefore ||
d.getElementsByTagName('base')[0];
if (insertBefore) {
s = _get(insertBefore, id);
if (s) {
Y.log('inserting before: ' + insertBefore, 'info', 'get');
s.parentNode.insertBefore(n, s);
}
} else {
h.appendChild(n);
}
// Y.log("Appending node: " + url, "info", "get");
// FireFox does not support the onload event for link nodes, so
// there is no way to make the css requests synchronous. This means
// that the css rules in multiple files could be applied out of order
// in this browser if a later request returns before an earlier one.
// Safari too.
if ((ua.webkit || ua.gecko) && q.type === 'css') {
_next(id, url);
}
},
/**
* Removes processed queues and corresponding nodes
* @method _autoPurge
* @private
*/
_autoPurge = function() {
if (purging) {
return;
}
purging = true;
var i, q;
for (i in queues) {
if (queues.hasOwnProperty(i)) {
q = queues[i];
if (q.autopurge && q.finished) {
_purge(q.tId);
delete queues[i];
}
}
}
purging = false;
},
/**
* Saves the state for the request and begins loading
* the requested urls
* @method queue
* @param {string} type the type of node to insert.
* @param {string} url the url to load.
* @param {object} opts the hash of options for this request.
* @return {object} transaction object.
* @private
*/
_queue = function(type, url, opts) {
opts = opts || {};
var id = 'q' + (qidx++), q,
thresh = opts.purgethreshold || Y.Get.PURGE_THRESH;
if (qidx % thresh === 0) {
_autoPurge();
}
queues[id] = Y.merge(opts, {
tId: id,
type: type,
url: url,
finished: false,
nodes: []
});
q = queues[id];
q.win = q.win || Y.config.win;
q.context = q.context || q;
q.autopurge = ('autopurge' in q) ? q.autopurge :
(type === 'script') ? true : false;
q.attributes = q.attributes || {};
q.attributes.charset = opts.charset || q.attributes.charset || 'utf-8';
_next(id);
return {
tId: id
};
};
/**
* Detects when a node has been loaded. In the case of
* script nodes, this does not guarantee that contained
* script is ready to use.
* @method _track
* @param {string} type the type of node to track.
* @param {HTMLElement} n the node to track.
* @param {string} id the id of the request.
* @param {string} url the url that is being loaded.
* @param {Window} win the targeted window.
* @param {int} qlength the number of remaining items in the queue,
* including this one.
* @param {Function} trackfn function to execute when finished
* the default is _next.
* @private
*/
_track = function(type, n, id, url, win, qlength, trackfn) {
var f = trackfn || _next;
// IE supports the readystatechange event for script and css nodes
// Opera only for script nodes. Opera support onload for script
// nodes, but this doesn't fire when there is a load failure.
// The onreadystatechange appears to be a better way to respond
// to both success and failure.
if (ua.ie) {
n.onreadystatechange = function() {
var rs = this.readyState;
if ('loaded' === rs || 'complete' === rs) {
// Y.log(id + " onreadstatechange " + url, "info", "get");
n.onreadystatechange = null;
f(id, url);
}
};
// webkit prior to 3.x is no longer supported
} else if (ua.webkit) {
if (type === 'script') {
// Safari 3.x supports the load event for script nodes (DOM2)
n.addEventListener('load', function() {
// Y.log(id + " DOM2 onload " + url, "info", "get");
f(id, url);
});
}
// FireFox and Opera support onload (but not DOM2 in FF) handlers for
// script nodes. Opera, but not FF, supports the onload event for link
// nodes.
} else {
n.onload = function() {
// Y.log(id + " onload " + url, "info", "get");
f(id, url);
};
n.onerror = function(e) {
_fail(id, e + ': ' + url);
};
}
};
_get = function(nId, tId) {
var q = queues[tId],
n = (L.isString(nId)) ? q.win.document.getElementById(nId) : nId;
if (!n) {
_fail(tId, 'target node not found: ' + nId);
}
return n;
};
/**
* Removes the nodes for the specified queue
* @method _purge
* @param {string} tId the transaction id.
* @private
*/
_purge = function(tId) {
var n, l, d, h, s, i, node, attr, insertBefore,
q = queues[tId];
if (q) {
n = q.nodes;
l = n.length;
d = q.win.document;
h = d.getElementsByTagName('head')[0];
insertBefore = q.insertBefore ||
d.getElementsByTagName('base')[0];
if (insertBefore) {
s = _get(insertBefore, tId);
if (s) {
h = s.parentNode;
}
}
for (i = 0; i < l; i = i + 1) {
node = n[i];
if (node.clearAttributes) {
node.clearAttributes();
} else {
for (attr in node) {
if (node.hasOwnProperty(attr)) {
delete node[attr];
}
}
}
h.removeChild(node);
}
}
q.nodes = [];
};
return {
/**
* The number of request required before an automatic purge.
* Can be configured via the 'purgethreshold' config
* property PURGE_THRESH
* @static
* @type int
* @default 20
* @private
*/
PURGE_THRESH: 20,
/**
* Called by the the helper for detecting script load in Safari
* @method _finalize
* @static
* @param {string} id the transaction id.
* @private
*/
_finalize: function(id) {
Y.log(id + ' finalized ', 'info', 'get');
setTimeout(function() {
_finish(id);
}, 0);
},
/**
* Abort a transaction
* @method abort
* @static
* @param {string|object} o Either the tId or the object returned from
* script() or css().
*/
abort: function(o) {
var id = (L.isString(o)) ? o : o.tId,
q = queues[id];
if (q) {
Y.log('Aborting ' + id, 'info', 'get');
q.aborted = true;
}
},
/**
* Fetches and inserts one or more script nodes into the head
* of the current document or the document in a specified window.
*
* @method script
* @static
* @param {string|string[]} url the url or urls to the script(s).
* @param {object} opts Options:
* <dl>
* <dt>onSuccess</dt>
* <dd>
* callback to execute when the script(s) are finished loading
* The callback receives an object back with the following
* data:
* <dl>
* <dt>win</dt>
* <dd>the window the script(s) were inserted into</dd>
* <dt>data</dt>
* <dd>the data object passed in when the request was made</dd>
* <dt>nodes</dt>
* <dd>An array containing references to the nodes that were
* inserted</dd>
* <dt>purge</dt>
* <dd>A function that, when executed, will remove the nodes
* that were inserted</dd>
* <dt>
* </dl>
* </dd>
* <dt>onTimeout</dt>
* <dd>
* callback to execute when a timeout occurs.
* The callback receives an object back with the following
* data:
* <dl>
* <dt>win</dt>
* <dd>the window the script(s) were inserted into</dd>
* <dt>data</dt>
* <dd>the data object passed in when the request was made</dd>
* <dt>nodes</dt>
* <dd>An array containing references to the nodes that were
* inserted</dd>
* <dt>purge</dt>
* <dd>A function that, when executed, will remove the nodes
* that were inserted</dd>
* <dt>
* </dl>
* </dd>
* <dt>onEnd</dt>
* <dd>a function that executes when the transaction finishes,
* regardless of the exit path</dd>
* <dt>onFailure</dt>
* <dd>
* callback to execute when the script load operation fails
* The callback receives an object back with the following
* data:
* <dl>
* <dt>win</dt>
* <dd>the window the script(s) were inserted into</dd>
* <dt>data</dt>
* <dd>the data object passed in when the request was made</dd>
* <dt>nodes</dt>
* <dd>An array containing references to the nodes that were
* inserted successfully</dd>
* <dt>purge</dt>
* <dd>A function that, when executed, will remove any nodes
* that were inserted</dd>
* <dt>
* </dl>
* </dd>
* <dt>context</dt>
* <dd>the execution context for the callbacks</dd>
* <dt>win</dt>
* <dd>a window other than the one the utility occupies</dd>
* <dt>autopurge</dt>
* <dd>
* setting to true will let the utilities cleanup routine purge
* the script once loaded
* </dd>
* <dt>purgethreshold</dt>
* <dd>
* The number of transaction before autopurge should be initiated
* </dd>
* <dt>data</dt>
* <dd>
* data that is supplied to the callback when the script(s) are
* loaded.
* </dd>
* <dt>insertBefore</dt>
* <dd>node or node id that will become the new node's nextSibling.
* If this is not specified, nodes will be inserted before a base
* tag should it exist. Otherwise, the nodes will be appended to the
* end of the document head.</dd>
* </dl>
* <dt>charset</dt>
* <dd>Node charset, default utf-8 (deprecated, use the attributes
* config)</dd>
* <dt>attributes</dt>
* <dd>An object literal containing additional attributes to add to
* the link tags</dd>
* <dt>timeout</dt>
* <dd>Number of milliseconds to wait before aborting and firing
* the timeout event</dd>
* <pre>
* Y.Get.script(
* ["http://yui.yahooapis.com/2.5.2/build/yahoo/yahoo-min.js",
* "http://yui.yahooapis.com/2.5.2/build/event/event-min.js"],
* {
* onSuccess: function(o) {
* this.log("won't cause error because Y is the context");
* Y.log(o.data); // foo
* Y.log(o.nodes.length === 2) // true
* // o.purge(); // optionally remove the script nodes
* // immediately
* },
* onFailure: function(o) {
* Y.log("transaction failed");
* },
* onTimeout: function(o) {
* Y.log("transaction timed out");
* },
* data: "foo",
* timeout: 10000, // 10 second timeout
* context: Y, // make the YUI instance
* // win: otherframe // target another window/frame
* autopurge: true // allow the utility to choose when to
* // remove the nodes
* purgetheshold: 1 // purge previous transaction before
* // next transaction
* });.
* </pre>
* @return {tId: string} an object containing info about the
* transaction.
*/
script: function(url, opts) {
return _queue('script', url, opts);
},
/**
* Fetches and inserts one or more css link nodes into the
* head of the current document or the document in a specified
* window.
* @method css
* @static
* @param {string} url the url or urls to the css file(s).
* @param {object} opts Options:
* <dl>
* <dt>onSuccess</dt>
* <dd>
* callback to execute when the css file(s) are finished loading
* The callback receives an object back with the following
* data:
* <dl>win</dl>
* <dd>the window the link nodes(s) were inserted into</dd>
* <dt>data</dt>
* <dd>the data object passed in when the request was made</dd>
* <dt>nodes</dt>
* <dd>An array containing references to the nodes that were
* inserted</dd>
* <dt>purge</dt>
* <dd>A function that, when executed, will remove the nodes
* that were inserted</dd>
* <dt>
* </dl>
* </dd>
* <dt>context</dt>
* <dd>the execution context for the callbacks</dd>
* <dt>win</dt>
* <dd>a window other than the one the utility occupies</dd>
* <dt>data</dt>
* <dd>
* data that is supplied to the callbacks when the nodes(s) are
* loaded.
* </dd>
* <dt>insertBefore</dt>
* <dd>node or node id that will become the new node's nextSibling</dd>
* <dt>charset</dt>
* <dd>Node charset, default utf-8 (deprecated, use the attributes
* config)</dd>
* <dt>attributes</dt>
* <dd>An object literal containing additional attributes to add to
* the link tags</dd>
* </dl>
* <pre>
* Y.Get.css("http://localhost/css/menu.css");
* </pre>
* <pre>
* Y.Get.css(
* ["http://localhost/css/menu.css",
* "http://localhost/css/logger.css"], {
* insertBefore: 'custom-styles' // nodes will be inserted
* // before the specified node
* });.
* </pre>
* @return {tId: string} an object containing info about the
* transaction.
*/
css: function(url, opts) {
return _queue('css', url, opts);
}
};
}();