| // Copyright 2011 The Closure Library Authors. All Rights Reserved. |
| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS-IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| |
| /** |
| * @fileoverview A utility to load JavaScript files via DOM script tags. |
| * Refactored from goog.net.Jsonp. Works cross-domain. |
| * |
| */ |
| |
| goog.provide('goog.net.jsloader'); |
| goog.provide('goog.net.jsloader.Error'); |
| goog.provide('goog.net.jsloader.ErrorCode'); |
| goog.provide('goog.net.jsloader.Options'); |
| |
| goog.require('goog.array'); |
| goog.require('goog.async.Deferred'); |
| goog.require('goog.debug.Error'); |
| goog.require('goog.dom'); |
| goog.require('goog.dom.TagName'); |
| |
| |
| /** |
| * The name of the property of goog.global under which the JavaScript |
| * verification object is stored by the loaded script. |
| * @type {string} |
| * @private |
| */ |
| goog.net.jsloader.GLOBAL_VERIFY_OBJS_ = 'closure_verification'; |
| |
| |
| /** |
| * The default length of time, in milliseconds, we are prepared to wait for a |
| * load request to complete. |
| * @type {number} |
| */ |
| goog.net.jsloader.DEFAULT_TIMEOUT = 5000; |
| |
| |
| /** |
| * Optional parameters for goog.net.jsloader.send. |
| * timeout: The length of time, in milliseconds, we are prepared to wait |
| * for a load request to complete. Default it 5 seconds. |
| * document: The HTML document under which to load the JavaScript. Default is |
| * the current document. |
| * cleanupWhenDone: If true clean up the script tag after script completes to |
| * load. This is important if you just want to read data from the JavaScript |
| * and then throw it away. Default is false. |
| * |
| * @typedef {{ |
| * timeout: (number|undefined), |
| * document: (HTMLDocument|undefined), |
| * cleanupWhenDone: (boolean|undefined) |
| * }} |
| */ |
| goog.net.jsloader.Options; |
| |
| |
| /** |
| * Scripts (URIs) waiting to be loaded. |
| * @type {Array<string>} |
| * @private |
| */ |
| goog.net.jsloader.scriptsToLoad_ = []; |
| |
| |
| /** |
| * Loads and evaluates the JavaScript files at the specified URIs, guaranteeing |
| * the order of script loads. |
| * |
| * Because we have to load the scripts in serial (load script 1, exec script 1, |
| * load script 2, exec script 2, and so on), this will be slower than doing |
| * the network fetches in parallel. |
| * |
| * If you need to load a large number of scripts but dependency order doesn't |
| * matter, you should just call goog.net.jsloader.load N times. |
| * |
| * If you need to load a large number of scripts on the same domain, |
| * you may want to use goog.module.ModuleLoader. |
| * |
| * @param {Array<string>} uris The URIs to load. |
| * @param {goog.net.jsloader.Options=} opt_options Optional parameters. See |
| * goog.net.jsloader.options documentation for details. |
| */ |
| goog.net.jsloader.loadMany = function(uris, opt_options) { |
| // Loading the scripts in serial introduces asynchronosity into the flow. |
| // Therefore, there are race conditions where client A can kick off the load |
| // sequence for client B, even though client A's scripts haven't all been |
| // loaded yet. |
| // |
| // To work around this issue, all module loads share a queue. |
| if (!uris.length) { |
| return; |
| } |
| |
| var isAnotherModuleLoading = goog.net.jsloader.scriptsToLoad_.length; |
| goog.array.extend(goog.net.jsloader.scriptsToLoad_, uris); |
| if (isAnotherModuleLoading) { |
| // jsloader is still loading some other scripts. |
| // In order to prevent the race condition noted above, we just add |
| // these URIs to the end of the scripts' queue and return. |
| return; |
| } |
| |
| uris = goog.net.jsloader.scriptsToLoad_; |
| var popAndLoadNextScript = function() { |
| var uri = uris.shift(); |
| var deferred = goog.net.jsloader.load(uri, opt_options); |
| if (uris.length) { |
| deferred.addBoth(popAndLoadNextScript); |
| } |
| }; |
| popAndLoadNextScript(); |
| }; |
| |
| |
| /** |
| * Loads and evaluates a JavaScript file. |
| * When the script loads, a user callback is called. |
| * It is the client's responsibility to verify that the script ran successfully. |
| * |
| * @param {string} uri The URI of the JavaScript. |
| * @param {goog.net.jsloader.Options=} opt_options Optional parameters. See |
| * goog.net.jsloader.Options documentation for details. |
| * @return {!goog.async.Deferred} The deferred result, that may be used to add |
| * callbacks and/or cancel the transmission. |
| * The error callback will be called with a single goog.net.jsloader.Error |
| * parameter. |
| */ |
| goog.net.jsloader.load = function(uri, opt_options) { |
| var options = opt_options || {}; |
| var doc = options.document || document; |
| |
| var script = goog.dom.createElement(goog.dom.TagName.SCRIPT); |
| var request = {script_: script, timeout_: undefined}; |
| var deferred = new goog.async.Deferred(goog.net.jsloader.cancel_, request); |
| |
| // Set a timeout. |
| var timeout = null; |
| var timeoutDuration = goog.isDefAndNotNull(options.timeout) ? |
| options.timeout : goog.net.jsloader.DEFAULT_TIMEOUT; |
| if (timeoutDuration > 0) { |
| timeout = window.setTimeout(function() { |
| goog.net.jsloader.cleanup_(script, true); |
| deferred.errback(new goog.net.jsloader.Error( |
| goog.net.jsloader.ErrorCode.TIMEOUT, |
| 'Timeout reached for loading script ' + uri)); |
| }, timeoutDuration); |
| request.timeout_ = timeout; |
| } |
| |
| // Hang the user callback to be called when the script completes to load. |
| // NOTE(user): This callback will be called in IE even upon error. In any |
| // case it is the client's responsibility to verify that the script ran |
| // successfully. |
| script.onload = script.onreadystatechange = function() { |
| if (!script.readyState || script.readyState == 'loaded' || |
| script.readyState == 'complete') { |
| var removeScriptNode = options.cleanupWhenDone || false; |
| goog.net.jsloader.cleanup_(script, removeScriptNode, timeout); |
| deferred.callback(null); |
| } |
| }; |
| |
| // Add an error callback. |
| // NOTE(user): Not supported in IE. |
| script.onerror = function() { |
| goog.net.jsloader.cleanup_(script, true, timeout); |
| deferred.errback(new goog.net.jsloader.Error( |
| goog.net.jsloader.ErrorCode.LOAD_ERROR, |
| 'Error while loading script ' + uri)); |
| }; |
| |
| // Add the script element to the document. |
| goog.dom.setProperties(script, { |
| 'type': 'text/javascript', |
| 'charset': 'UTF-8', |
| // NOTE(user): Safari never loads the script if we don't set |
| // the src attribute before appending. |
| 'src': uri |
| }); |
| var scriptParent = goog.net.jsloader.getScriptParentElement_(doc); |
| scriptParent.appendChild(script); |
| |
| return deferred; |
| }; |
| |
| |
| /** |
| * Loads a JavaScript file and verifies it was evaluated successfully, using a |
| * verification object. |
| * The verification object is set by the loaded JavaScript at the end of the |
| * script. |
| * We verify this object was set and return its value in the success callback. |
| * If the object is not defined we trigger an error callback. |
| * |
| * @param {string} uri The URI of the JavaScript. |
| * @param {string} verificationObjName The name of the verification object that |
| * the loaded script should set. |
| * @param {goog.net.jsloader.Options} options Optional parameters. See |
| * goog.net.jsloader.Options documentation for details. |
| * @return {!goog.async.Deferred} The deferred result, that may be used to add |
| * callbacks and/or cancel the transmission. |
| * The success callback will be called with a single parameter containing |
| * the value of the verification object. |
| * The error callback will be called with a single goog.net.jsloader.Error |
| * parameter. |
| */ |
| goog.net.jsloader.loadAndVerify = function(uri, verificationObjName, options) { |
| // Define the global objects variable. |
| if (!goog.global[goog.net.jsloader.GLOBAL_VERIFY_OBJS_]) { |
| goog.global[goog.net.jsloader.GLOBAL_VERIFY_OBJS_] = {}; |
| } |
| var verifyObjs = goog.global[goog.net.jsloader.GLOBAL_VERIFY_OBJS_]; |
| |
| // Verify that the expected object does not exist yet. |
| if (goog.isDef(verifyObjs[verificationObjName])) { |
| // TODO(user): Error or reset variable? |
| return goog.async.Deferred.fail(new goog.net.jsloader.Error( |
| goog.net.jsloader.ErrorCode.VERIFY_OBJECT_ALREADY_EXISTS, |
| 'Verification object ' + verificationObjName + ' already defined.')); |
| } |
| |
| // Send request to load the JavaScript. |
| var sendDeferred = goog.net.jsloader.load(uri, options); |
| |
| // Create a deferred object wrapping the send result. |
| var deferred = new goog.async.Deferred( |
| goog.bind(sendDeferred.cancel, sendDeferred)); |
| |
| // Call user back with object that was set by the script. |
| sendDeferred.addCallback(function() { |
| var result = verifyObjs[verificationObjName]; |
| if (goog.isDef(result)) { |
| deferred.callback(result); |
| delete verifyObjs[verificationObjName]; |
| } else { |
| // Error: script was not loaded properly. |
| deferred.errback(new goog.net.jsloader.Error( |
| goog.net.jsloader.ErrorCode.VERIFY_ERROR, |
| 'Script ' + uri + ' loaded, but verification object ' + |
| verificationObjName + ' was not defined.')); |
| } |
| }); |
| |
| // Pass error to new deferred object. |
| sendDeferred.addErrback(function(error) { |
| if (goog.isDef(verifyObjs[verificationObjName])) { |
| delete verifyObjs[verificationObjName]; |
| } |
| deferred.errback(error); |
| }); |
| |
| return deferred; |
| }; |
| |
| |
| /** |
| * Gets the DOM element under which we should add new script elements. |
| * How? Take the first head element, and if not found take doc.documentElement, |
| * which always exists. |
| * |
| * @param {!HTMLDocument} doc The relevant document. |
| * @return {!Element} The script parent element. |
| * @private |
| */ |
| goog.net.jsloader.getScriptParentElement_ = function(doc) { |
| var headElements = doc.getElementsByTagName(goog.dom.TagName.HEAD); |
| if (!headElements || goog.array.isEmpty(headElements)) { |
| return doc.documentElement; |
| } else { |
| return headElements[0]; |
| } |
| }; |
| |
| |
| /** |
| * Cancels a given request. |
| * @this {{script_: Element, timeout_: number}} The request context. |
| * @private |
| */ |
| goog.net.jsloader.cancel_ = function() { |
| var request = this; |
| if (request && request.script_) { |
| var scriptNode = request.script_; |
| if (scriptNode && scriptNode.tagName == 'SCRIPT') { |
| goog.net.jsloader.cleanup_(scriptNode, true, request.timeout_); |
| } |
| } |
| }; |
| |
| |
| /** |
| * Removes the script node and the timeout. |
| * |
| * @param {Node} scriptNode The node to be cleaned up. |
| * @param {boolean} removeScriptNode If true completely remove the script node. |
| * @param {?number=} opt_timeout The timeout handler to cleanup. |
| * @private |
| */ |
| goog.net.jsloader.cleanup_ = function(scriptNode, removeScriptNode, |
| opt_timeout) { |
| if (goog.isDefAndNotNull(opt_timeout)) { |
| goog.global.clearTimeout(opt_timeout); |
| } |
| |
| scriptNode.onload = goog.nullFunction; |
| scriptNode.onerror = goog.nullFunction; |
| scriptNode.onreadystatechange = goog.nullFunction; |
| |
| // Do this after a delay (removing the script node of a running script can |
| // confuse older IEs). |
| if (removeScriptNode) { |
| window.setTimeout(function() { |
| goog.dom.removeNode(scriptNode); |
| }, 0); |
| } |
| }; |
| |
| |
| /** |
| * Possible error codes for jsloader. |
| * @enum {number} |
| */ |
| goog.net.jsloader.ErrorCode = { |
| LOAD_ERROR: 0, |
| TIMEOUT: 1, |
| VERIFY_ERROR: 2, |
| VERIFY_OBJECT_ALREADY_EXISTS: 3 |
| }; |
| |
| |
| |
| /** |
| * A jsloader error. |
| * |
| * @param {goog.net.jsloader.ErrorCode} code The error code. |
| * @param {string=} opt_message Additional message. |
| * @constructor |
| * @extends {goog.debug.Error} |
| * @final |
| */ |
| goog.net.jsloader.Error = function(code, opt_message) { |
| var msg = 'Jsloader error (code #' + code + ')'; |
| if (opt_message) { |
| msg += ': ' + opt_message; |
| } |
| goog.net.jsloader.Error.base(this, 'constructor', msg); |
| |
| /** |
| * The code for this error. |
| * |
| * @type {goog.net.jsloader.ErrorCode} |
| */ |
| this.code = code; |
| }; |
| goog.inherits(goog.net.jsloader.Error, goog.debug.Error); |