js/xpconnect/idl/mozIJSSubScriptLoader.idlScriptable
This interface can be used from privileged JavaScript to load and run JavaScript code from the given URL at runtime.
66
Introduced
Gecko 1.0
Inherits from: nsISupports Last changed in Gecko 28 (Firefox 28 / Thunderbird 28 / SeaMonkey 2.25 / Firefox OS 1.3)

Implemented by: @mozilla.org/moz/jssubscript-loader;1. To get this service, use:

var mozIJSSubScriptLoader = Components.classes["@mozilla.org/moz/jssubscript-loader;1"]
                            .getService(Components.interfaces.mozIJSSubScriptLoader);
Note: See Components.utils.import for another way to import JavaScript code.

Method overview

jsval loadSubScript(in string url, in Object targetObj Optional, in string charset Optional);
jsval loadSubScriptWithOptions(in string url, in Object options);

Methods

loadSubScript()

Synchronously loads and executes the script from the specified URL. As of Gecko 8.0, scripts are loaded from the startup cache where possible.

The loaded script is executed with the principal associated with the target object.

Any top-level functions or variables created by the loaded script via var are created as properties of the targetObj target object (but things declared via let and const are NOT). Additionally, properties of the targetObj target object can be referred to as variables in the loaded script.

If the script returns a value, it will be returned by this method.

Note: This method must only be called from JavaScript!

jsval loadSubScript(
  in string url,
  in Object targetObj Optional,
  in string charset   Optional,
);
Example
let context = {};
Services.scriptloader.loadSubScript("chrome://my-package/content/foo-script.js",
                                    context, "UTF-8" /* The script's encoding */);
Parameters
url
The URL pointing to the script to load. It must be a local chrome:, resource: or file: URL (see bug 307686 and bug 418356).

Note: In versions of Gecko prior to Gecko 1.9, you could use data: URLs as well, but this introduced security concerns, and is no longer permitted.

targetObj
The object to use as the scope object for the script being executed. This is where var declarations in the script will be placed.  It defaults to the global object of the caller.  Note that let and const declarations in the script will be placed on a syntactic scope that is not an object at all, and will not be available to the caller of loadSubScript.  Note: Undeclared variables in the loaded script will be created as global variables in the caller (ie.: in the caller's global object). This object will be searched for variables that cannot be resolved in the subscript scope.
charset
An optional string to specify the character encoding of the file. If absent, the file is interpreted as ASCII.

loadSubScriptWithOptions()

Same as loadSubScript(), except that parameters after url are expressed as an object, and a new ignoreCache option is available.

Note: This method must only be called from JavaScript!

jsval loadSubScriptWithOptions(
  in string url,
  in Object options
);
Parameters
url
The URL pointing to the script to load. It must be a local chrome:, resource: or file: URL.
options
An object that may include any of these parameters:

 

Property Type Description
target object The object to use as the scope object for the script being executed. It defaults to the global object of the caller. Note: Undeclared variables in the loaded script will be created as global variables in the caller (ie.: in the caller's global object). This object will be searched for variables that cannot be resolved in the subscript scope.
charset string An optional string to specify the character encoding of the file. If absent, the file is interpreted as ASCII.
ignoreCache boolean If present and set to true, the cache will be bypassed when reading the file.

See also