mozilla

Revision 310379 of Components.utils.import

  • Revision slug: Components.utils.import
  • Revision title: Components.utils.import
  • Revision id: 310379
  • Created:
  • Creator: Hans.Hokke
  • Is current revision? No
  • Comment Added reference to deprecation of enableprivilege.

Revision Content

{{ Gecko_minversion_header("1.9") }}

This method was introduced in Firefox 3 and is used for sharing code between different scopes easily. For example, you can import XPCOMUtils.jsm to avoid copy/pasting long XPCOM component registration boilerplate in your component files.

See Using JavaScript code modules for more details.

{{ gecko_callout_heading("2") }}

Prior to Gecko 2.0 {{ geckoRelease("2") }}, JavaScript code modules could only be loaded using file: or resource: URLs. Gecko 2.0 adds support for loading modules from chrome: URLs, even those inside JAR archives.

Due to deprecation of enablePrivilege this functionality can not be used in web pages. EnablePrivilege is disabled in Firefox 15 and will be removed in Firefox 17.

Use in extensions is unrestricted.

Syntax

Components.utils.import( url [, scope ] );

or (if you want to avoid getting pesky compiler erros about missing . after operator)

Components.utils["import"]( url [, scope ] );

Parameters

url
A string of the URL of the script to be loaded. The URL must point to a file on the disk, possibly in a JAR.
scope
An optional object to import onto; if omitted, the global object is used.

Example

Components.utils.import("resource://gre/modules/XPCOMUtils.jsm");

Difference from mozIJSSubScriptLoader

The differences from {{ Interface("mozIJSSubScriptLoader") }}:

  • The behavior when importing/loading the same code from different locations:
    • the subscript loader evaluates the specified code each time it is invoked, with the caller's global object.
    • Components.utils.import evaluates the code of each module only once, in its own scope.

    For example:

    var scope1 = {}, scope2 = {};
    Components.utils.import("resource://gre/modules/JSON.jsm", scope1);
    Components.utils.import("resource://gre/modules/JSON.jsm", scope2);
    assert(scope2.XPCOMUtils === scope1.XPCOMUtils);
    

    ...returns true, whereas:

    var someURL = "resource://gre/modules/JSON.jsm"; 
    var obj1 = {}, obj2 = {}; 
    var loader = Components.classes["@mozilla.org/moz/jssubscript-loader;1"]
                           .getService(Components.interfaces.mozIJSSubScriptLoader); 
    loader.loadSubScript(someURL, obj1); 
    loader.loadSubScript(someURL, obj2);
    assert(obj2 === obj1);
    

    ...returns false.

    This means Components.utils.import is better suited for efficient sharing of code (and data?) between JS scripts running in different scope.

Additional Resources

  • {{ Bug(238324) }}
  • The documentation in {{ Source("js/xpconnect/idl/xpccomponents.idl", "xpccomponents.idl") }}
  • The tests in {{ Source("js/xpconnect/tests/unit/") }}

 

 

{{ languages( { "es": "es/Components.utils.import", "fr": "fr/Components.utils.import", "ja": "ja/Components.utils.import" } ) }}

Revision Source

<p>{{ Gecko_minversion_header("1.9") }}</p>
<p>This method was introduced in <a href="/en/Firefox_3_for_developers" title="en/Firefox_3_for_developers">Firefox 3</a> and is used for sharing code between different scopes easily. For example, you can import <a href="/en/JavaScript_code_modules/XPCOMUtils.jsm" title="en/XPCOMUtils.jsm">XPCOMUtils.jsm</a> to avoid copy/pasting long XPCOM component registration boilerplate in your component files.</p>
<p>See <a href="/en/JavaScript_code_modules/Using" title="en/Using_JavaScript_code_modules">Using JavaScript code modules</a> for more details.</p>
<div class="geckoVersionNote">
  <p>{{ gecko_callout_heading("2") }}</p>
  <p>Prior to Gecko 2.0 {{ geckoRelease("2") }}, JavaScript code modules could only be loaded using <strong>file:</strong> or <strong>resource:</strong> URLs. Gecko 2.0 adds support for loading modules from <strong>chrome:</strong> URLs, even those inside JAR archives.</p>
</div>
<div class="warning">
  <p name="Syntax">Due to <a href="https://developer.mozilla.org/docs/Bypassing_Security_Restrictions_and_Signing_Code" title="https://developer.mozilla.org/en-US/docs/Bypassing_Security_Restrictions_and_Signing_Code">deprecation of enablePrivilege</a> this functionality can not be used in web pages. EnablePrivilege is disabled in Firefox 15 and will be removed in Firefox 17.</p>
  <p name="Syntax">Use in extensions is unrestricted.</p>
</div>
<h3 id="Syntax" name="Syntax">Syntax</h3>
<pre class="eval">
Components.utils.import( <em>url</em> [, <em>scope</em> ] );

or (if you want to avoid getting pesky compiler erros about missing . after operator)

Components.utils["import"]( <em>url</em> [, <em>scope</em> ] );</pre>
<h3 id="Parameters" name="Parameters">Parameters</h3>
<dl>
  <dt>
    <code>url</code></dt>
  <dd>
    A string of the URL of the script to be loaded. The URL must point to a file on the disk, possibly in a JAR.</dd>
  <dt>
    <code>scope</code></dt>
  <dd>
    An optional object to import onto; if omitted, the global object is used.</dd>
</dl>
<h3 id="Example" name="Example">Example</h3>
<pre class="eval">
Components.utils.import("<a class="external" href="resource://gre/modules/XPCOMUtils.jsm" rel="freelink">resource://gre/modules/XPCOMUtils.jsm</a>");
</pre>
<h3 id="Difference_from_mozIJSSubScriptLoader" name="Difference_from_mozIJSSubScriptLoader">Difference from mozIJSSubScriptLoader</h3>
<p>The differences from {{ Interface("mozIJSSubScriptLoader") }}:</p>
<ul>
  <li>The behavior when importing/loading the same code from different locations:
    <ul>
      <li>the subscript loader evaluates the specified code each time it is invoked, with the caller's global object.</li>
      <li><code>Components.utils.import</code> evaluates the code of each module only once, in its own scope.</li>
    </ul>
    <p>For example:</p>
    <pre class="eval">
var scope1 = {}, scope2 = {};
Components.utils.import("<a class="external" href="resource://gre/modules/JSON.jsm" rel="freelink">resource://gre/modules/JSON.jsm</a>", scope1);
Components.utils.import("<a class="external" href="resource://gre/modules/JSON.jsm" rel="freelink">resource://gre/modules/JSON.jsm</a>", scope2);
assert(scope2.XPCOMUtils === scope1.XPCOMUtils);
</pre>
    <p>...returns <code>true</code>, whereas:</p>
    <pre class="eval">
var someURL = "<a class="external" href="resource://gre/modules/JSON.jsm" rel="freelink">resource://gre/modules/JSON.jsm</a>"; 
var obj1 = {}, obj2 = {}; 
var loader = Components.classes["@mozilla.org/moz/jssubscript-loader;1"]
                       .getService(Components.interfaces.mozIJSSubScriptLoader); 
loader.loadSubScript(someURL, obj1); 
loader.loadSubScript(someURL, obj2);
assert(obj2 === obj1);
</pre>
    <p>...returns <code>false</code>.</p>
    <p>This means <code>Components.utils.import</code> is better suited for efficient sharing of code (and data?) between JS scripts running in different scope.</p>
  </li>
</ul>
<h3 id="Additional_Resources" name="Additional_Resources">Additional Resources</h3>
<ul>
  <li>{{ Bug(238324) }}</li>
  <li>The documentation in {{ Source("js/xpconnect/idl/xpccomponents.idl", "xpccomponents.idl") }}</li>
  <li>The tests in {{ Source("js/xpconnect/tests/unit/") }}</li>
</ul>
<p>&nbsp;</p>
<p>&nbsp;</p>
<p>{{ languages( { "es": "es/Components.utils.import", "fr": "fr/Components.utils.import", "ja": "ja/Components.utils.import" } ) }}</p>
Revert to this revision