Appendix D: Loading Scripts

Most add-ons and XUL Runner applications provide their primary functionality by loading and executing JavaScript code. Because there are such a diverse array of add-ons, and because the needs of developers have grown organically over time, the Gecko runtime provides a number of means to dynamically load and execute JavaScript files. Each of these means has its own advantages and disadvantages, as well as its own quirks which may trap the unwary. Below is an overview of the more common means of loading scripts, along with some of their primary advantages, disadvantages, quirks, and use cases.

The examples below which make use of the Services global assume that you're previously imported the Services.jsm module. As this module only exists on Firefox 4 and other Gecko 2-based platforms, the services in question will have to be manually loaded on other platforms.

<script> tags

XUL script tags are traditionally the primary means of loading scripts for extension developers. These tags are generally inserted into XUL overlay files or other XUL documents, after which they are automatically loaded into the context of the XUL window in question and executed immediately and synchronously.

Advantages

• Familiarity: These tags are very similar to the HTML script tags familiar to most web developers.
• Simplicity: The simple, declarative nature of these tags make them easy to find and understand at a glance.
• Speed: Script tags may or may not be loaded from pre-compiled bytecode in the fastload cache (Gecko 1.x) or startup cache (Gecko 2), which means they don't necessarily need to read as source and compiled with each restart.
• Flexibility: Script tags provide a means to specify the character set and JavaScript version of the scripts to be loaded, which many other methods do not.
• Debuggable: development tools support debugging JavaScript loaded by script tags

Disadvantages

• Scoping: Scripts loaded via script tags share the global scope with all other scripts loaded into the same window. These tags provide no means to load scripts into a private or otherwise specific scope.
• Speed: Even if these scripts are loaded from a cache, only read and compile time are reduced. The scripts still need to execute all of their initialization code and allocate and initialize all of their data structures each time the script is loaded.
• Loading: Script loaded via script tags run in partially loaded documents. Problems can ensue if the script immediately attempts to access DOM nodes. This is easily resolved by deferring the work to a dynamically added onload hander. (A standalone XUL window can use an onload attribute.)

Example

The following overlay will load the script “overlay.js” from the same directory as the overlay file into the window which it overlays. The script will be read with the UTF-8 encoding, based on the encoding of the overlay, and will execute as JavaScript version 1.8, based on the version specified in the script tag.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE overlay>
<overlay id="script-overlay"
         xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
    <script type="application/javascript;version=1.8" src="overlay.js"/>
</overlay>

evalInSandbox

The Components.utils.evalInSandbox method may be used to load arbitrary code into Components.utils.Sandbox objects. JavaScript files or URLs may be loaded in this manner by first retrieving their contents into memory using an XMLHttpRequest. This is the method used by Jetpack's securable module system to load nearly all executable code.

Advantages

• Namespacing: Since scripts executed via evalInSandbox run in a defined namespace, global namespace contamination and the resultant extension compatibility issues are not usually a problem.
• Flexibility: The evalInSandbox method accepts several parameters, including the URL, line number, and JavaScript version of the file from which the code being evaluated was extracted. This information is invaluable for debugging, and the flexibility with which it can be specified makes this method useful for extracting JavaScript from a number of file formats other than raw JavaScript scripts. Additionally, as Sandbox objects can be created with an arbitrary prototype object, the evaluated code can be given access to the global properties of any existing scope.
• Security: Sandbox objects are initialized with a security principal object, or otherwise a window or URL from which to derive one. This means that evalInSandbox can be used to execute code with a specified privilege level rather than full chrome privileges. Beyond this, the scope of the Sandbox can be augmented or rarified to add or remove privileges as necessary. Under ordinary circumstances, native objects passed out of Sandboxes are wrapped in XrayWrapper objects, which means that only native properties of these objects are directly exposed to privileged code. This behavior can be reversed by setting the wantsXrays parameter to false when constructing the Sandbox.

Disadvantages

• Performance: There are several significant performance disadvantages inherent in this method:
  • There is currently no way to load code into sandboxes from a cache. This means that code must be compiled and executed anew each time it is loaded, which has a significant overhead for large code bases.
  • In addition to compile time, reading files synchronously from disk has its own overhead, and XMLHttpRequests have significantly more overhead than native loading methods.
  • Although wary authors can choose to cache instances of their modules so that modules are loaded only once globally, this method can be easily misused to re-load scripts for each new window where they would be better loaded only once globally per session.
  • Because Sandbox objects are evaluated in their own javascript compartment, they are separated by a membrane from other JavaScript code. This means that any and all JavaScript objects passed in our out of them are wrapped in inter-compartment Proxy objects, which consume additional memory and add an extra layer of complexity to all property accesses and method calls.
• JavaScript compartments: As noted above, each Sandbox executes in its own javascript compartment. In addition to the possible performance concerns, passing data between these compartments is not entirely transparent. Some known issues include:
  • E4X XML objects cannot be wrapped for passage between compartments: bug 613142
  • There are a number of type detection issues, including:
    • String.replace does not recognize RegExp objects from foreign compartments: bug 633830
• Debugging: Support for Sandbox evaluation in development tools is uneven. Chromebug supports Firebug based Sandboxes.

Examples

The following code will execute a simple script in a Sandbox with the privilege level of the current content page. The globals of the current content window will be available in the scripts global scope. In stack traces, the script will appear to have been loaded from the file "zz-9://plural/zed/alpha", line 42.

// Use the current content window as the execution context.
// To make properties defined by scripts executing on the page
// available to your sandbox script, use content.wrappedJSObject
// instead.
let context = content;
// Create the Sandbox
let sandbox = Components.utils.Sandbox(context, {
    // Make properties of the context object available via the
    // script's global scope
    sandboxPrototype: context,
    // Wrap objects retrieved from the sandbox in XPCNativeWrappers.
    // This is the default action.
    wantXrays: true
});
// The script that will be executed:
let script = String();
// Evaluate the script:
Components.utils.evalInSandbox(script, sandbox,
                               // The JavaScript version
                               "1.8",
                               // The apparent script filename:
                               "zz-9://plural/zed/alpha",
                               // The apparent script starting line number:
                               42);

The following code will execute a simple script loaded from a local file in the same directory as the current script. The script will execute in the same security context as the current script and will have access to the same globals, but any new globals it creates will be accessible only to the script itself. Objects passed out of the sandbox will not be wrapped in XPCNativeWrappers but will still be wrapped in inter-compartment proxies.

const XMLHttpRequest = Components.Constructor("@mozilla.org/xmlextras/xmlhttprequest;1",
                                              "nsIXMLHttpRequest",
                                              "open");
function loadScript(name, context) {
    // Create the Sandbox
    let sandbox = Components.utils.Sandbox(context, {
        sandboxPrototype: context,
        wantXrays: false
    });
    // Get the caller's filename
    let file = Components.caller.stack.filename;
    // Strip off any prefixes added by the sub-script loader
    // and the trailing filename
    let directory = file.replace(/.* -> |[^\/]+$/g, "");
    let scriptName = directory + name;
    // Read the script
    let xmlhttp = XMLHttpRequest("GET", scriptName, false);
    xmlhttp.overrideMimeType("text/plain");
    xmlhttp.send();
    let script = xmlhttp.textContent;
    // Evaluate the script:
    Components.utils.evalInSandbox(script, sandbox,
                                   "1.8", scriptName, 0);
}
// Use the current global object.
// The following may be used instead at the top-level:
//
// let context = this
if (Components.utils.getGlobalForObject)
    // Gecko 2.x
    var context = Components.utils.getGlobalForObject({});
else
    // Gecko 1.x
    context = {}.__parent__;
loadScript("script.js", context);

The Sub-Script Loader

The mozIJSSubScriptLoader can be used to load local scripts from the chrome:, resource:, and file: protocols into any JavaScript object. Any new globals created by this script are defined as properties of this object. Additionally, any properties of the target object are available as variables in the script's global namespace, along with as any properties of the global associated with the target object. These scripts execute with the same privileges and restrictions of the global associated with the target object, and this method can therefore also be used when with Sandbox objects with the same effect as evalInSandbox and into content windows with the same effect as injecting script tags into their documents.

Advantages

• Namespacing: Global namespace contamination and the resultant extension compatibility issues can often be avoided by loading sub-scripts into private namespaces.
• Flexibility: The sub-script loader can load scripts into a variety of different namespaces for a wide variety of uses, and as of Gecko 2 allows the character set of the script to be specified.
• Performance: As of Gecko 8.0, scripts loaded via mozIJSSubScriptLoader.loadSubScript() are loaded from a cache. Unlike modules, however, scripts are still executed each time they are loaded and therefore still suffer performance and memory disadvantages over that method.
• When loading into a Sandbox object, the same advantages apply as above.

Disadvantages

• Performance: Prior to Gecko 8.0, scripts loaded via mozIJSSubScriptLoader.loadSubScript() are not loaded from a cache, and therefore must be read and compiled each time they are loaded which has a significant overhead for large code bases. Although wary authors can choose to cache instances of their modules so that modules are loaded only once globally, this method can be easily misused to re-load scripts for each new window where they would be better loaded only once globally per session.
• Non-chrome files loaded in this manner will have the current filename prefixed to the filename in their debugging information. For instance, the file “resource://foo/bar.js” loaded from “resource://foo/baz.js” will appear as “resource://foo/baz.js -> resource://foo/bar.js” in stack traces.
• When loading into a Sandbox object, the same disadvantages apply as above.

Examples

The following code will load a script into its own context. The script will execute with the security principal of and have access to the global properties of the current global.

let context = {};
Services.scriptloader.loadSubScript("chrome://my-package/content/foo-script.js",
                                    context, "UTF-8" /* The script's encoding */);

The following code will execute a simple script loaded from a local file in the same directory as the current script. The script will execute in the same security context as the current script and will have access to the same globals, but any new globals it creates will be accessible only to the script itself. Objects passed out of the sandbox will not be wrapped in XPCNativeWrappers but will still be wrapped in inter-compartment proxies.

function loadScript(name, context) {
    // Create the Sandbox
    let sandbox = Components.utils.Sandbox(context, {
        sandboxPrototype: context,
        wantXrays: false
    });
    // Get the caller's filename
    let file = Components.caller.stack.filename;
    // Strip off any prefixes added by the sub-script loader
    // and the trailing filename
    let directory = file.replace(/.* -> |[^\/]+$/g, "");
    Services.scriptloader.loadSubScript(directory + name,
                                        sandbox, "UTF-8");
}
loadScript("foo.js", this);

JavaScript modules

JavaScript modules are used to efficiently load scripts into their own global namespaces. Because these scripts are loaded from a bytecode cache, and the same scripts are loaded only once per session no matter how many times they are imported, this is one of the most performant methods of script loading.

Advantages

• Performance: JavaScript modules are stored in a pre-compiled format in a cache, and therefore load with significantly less overhead than other types of scripts. Additionally, scripts are loaded only once globally per session, and therefore have virtually no overhead for multiple imports.
• Namespacing: JavaScript modules, like JavaScript components, are loaded into their own private scope. Namespace contamination and the resulting compatibility issues are only an issue when they are imported into shared global namespaces.
• Data sharing: As modules are loaded only once globally, every import has access to the same data and global variables no matter what context or window it was imported from. JavaScript modules can therefor be used for communication and data sharing between otherwise isolated contexts. Note that this isn't true for Multiprocess Firefox, because for each process the modules are loaded separately.
• Debugging: Chromebug (at least) can list Component.utils modules and single step through them.

Disadvantages

• Namespacing: As modules always execute with their own namespace, they have no direct access to the DOM or window properties of windows or documents, and therefore must often pass around references to these objects and any document-specific state data that they require.

Examples

The following code will import a module into the current global scope. All variables named in the target script's EXPORTED_SYMBOLS global array will be copied into the current execution context.

Components.utils.import("resource://my-package/my-module.jsm");

The following function will import an arbitrary module into a singleton object, which it returns. If the argument is not an absolute path, the module is imported relative to the caller's filename.

function module(uri) {
    if (!/^[a-z-]+:/.exec(uri))
        uri = /([^ ]+\/)[^\/]+$/.exec(Components.stack.caller.filename)[1] + uri + ".jsm";
    let obj = {};
    Components.utils.import(uri, obj);
    return obj;
}

Given the above code, the following code will import the module "my-module.jsm" from the current directory and define the symbols foo and bar from that module in the current scope. It will also import the symbol Services from the standard Services.jsm module.

const { Services } = module("resource://gre/modules/Services.jsm");
const { bar, foo } = module("my-module");

DOM Workers: Worker and ChromeWorker

DOM Workers can be used to load scripts into their own global contexts which run in their own threads. In order to ensure thread safety, these contexts are extremely limited, can't be passed JavaScript objects, and have no access to the DOM. All communication between these contexts and outer contexts is marshalled through JSON encoding and decoding. ChromeWorkers also have access to ctypes and a limited number of thread safe XPCOM classes, but are otherwise limited to simple computation based on data passed via messages and XMLHttpRequests.

Advantages

• Asynchronous: Workers execute asynchronously in their own threads, which means that they have limited risk of interfering with the main thread. They may safely perform synchronous XMLHttpRequests or other intensive computation which would normally need to be broken up into multiple callbacks.
• Safety: As workers have no access to objects which might cause a crash or deadlock when executed re-entrantly or by spinning the event loop, there are significant safety advantages over other methods of asynchronous execution.

Disadvantages

• Limited scoping: As data from the main thread may only be accessed via JSON message passing, there are significant difficulties in performing many operations in Worker scopes.
• DOM Access: As there is no DOM access in Worker scopes, XMLHttpRequests may not easily be used with XML or HTML sources, and should instead only be used with JSON or other text-based sources.
• Debugging: JSD knows nothing about Workers and no JavaScript debuggers work on them.