874
edits
Changes
added docs, moved from JEP 28
* Registering callbacks that perform cleanup tasks when modules are unloaded.
== Code Examples Specification ==
<tt>securable-module.js</tt> allows for the recursive loading and sandboxing of SecurableModules with any desired security principal. === XULRunner extensionUsage === This module can be included via a <tt><script></tt> tag in a chrome-privileged document, in imported as a JS module via <tt>Components.utils.import()</tt>, or recursively imported as a SecurableModule via <tt>require()</tt>. ==== In a chrome-privileged document ====
Assume that the following code is contained in a file at <tt>chrome://some_extension/content/foo.html</tt>.
</pre>
Booster functionality should be just as easy to access if the
Note that unlike the previous example, we can't provide a relative directory name for <tt>rootPath</tt> because JS modules don't conventionally have a concept of relative directories (and we won't introduce such a concept here to reduce potential confusion).
==== In a SecurableModule ====
If <tt>securable-module.js</tt> is itself placed on a <tt>SecurableModule.Loader</tt>'s <tt>rootPath</tt>, it can be included via a call to <tt>require()</tt> and used within the context of its parent Loader. For this to work, however, all code must be executed using the system principal.
=== Loader Objects ===
Loader objects encapsulate the sandboxed loading of SecurableModules and the execution of code that relies upon them.
<tt>Loader.'''runScript'''(''options'')</tt>
Runs JavaScript code in the context of the Loader. ''options'' is an object with the following keys:
{|cellpadding="5" cellspacing="0" border="1" width="100%"
|<tt>contents</tt>
|A string of JavaScript code.
|-
|<tt>filename</tt>
|An absolute URL naming the file from which the code originates; useful for error reporting and debugging. If omitted, this option defaults to <tt>"<string>"</tt>.
|-
|<tt>lineNo</tt>
|An integer representing the line from the file which the beginning of the code corresponds to. If ommitted, this option defaults to <tt>1</tt>.
|-
|<tt>jsVersion</tt>
|A string representing the JavaScript version that the code should be interpreted under. If omitted, this options defaults to the latest version of JavaScript supported by the platform.
|}
This method returns the most recent value evaluated by the given code.
<tt>Loader.'''runScript'''(''code'')</tt>
If ''code'' is a string of JavaScript code, this is a convenient shorthand for <tt>Loader.runScript({contents: code}}</tt>.
=== Functions ===
<tt>SecurableModule.'''Loader'''(''options'')</tt>
Creates a new SecurableModule Loader. ''options'' is an object with the following keys:
{|cellpadding="5" cellspacing="0" border="1" width="100%"
|<tt>rootPaths</tt>
|A list of absolute URLs that will be searched, in order, for SecurableModules when <tt>require()</tt> is called by any code executing within the context of the Loader.
|-
|<tt>rootPath</tt>
|A single absolute URL; this is a convenience option, synonymous with setting <tt>rootPaths</tt> to an array containing a single URL.
|-
|<tt>defaultPrincipal</tt>
|A string representing the default principal given to any code that is executed by the Loader. This can be <tt>"system"</tt>, in which case code executed has full chrome access (including access to the <tt>Components</tt> object which allows it to access the Mozilla platform unrestricted). Alternatively, it can be a URL, such as <tt><nowiki>"http://www.foo.com"</nowiki></tt>, in which case it is treated like web content. If left unspecified, the default value of this option is <tt><nowiki>"http://www.mozilla.org"</nowiki></tt>.
|-
|<tt>globals</tt>
|An object containing the names and values of all variables that will be injected into the global scope of all code executed by the Loader.
|}
== Reference Implementation ==
