mozilla

Revision 509079 of content/symbiont

  • Revision slug: Mozilla/Add-ons/SDK/Low-Level_APIs/content_symbiont
  • Revision title: content/symbiont
  • Revision id: 509079
  • Created:
  • Creator: wbamberg
  • Is current revision? No
  • Comment

Revision Content

Unstable

Used by SDK modules that can load web content and attach content scripts to it.

Usage

A Symbiont loads the specified contentURL and content scripts into a frame, and sets up an asynchronous channel between the content scripts and the add-on code, enabling them to exchange messages using the port or postMessage APIs. You map optionally pass a frame into the Symbiont's constructor: if you don't, then a new hidden frame will be created to host the content.

This trait is composed from the Loader and Worker traits. It inherits functions to load and configure content scripts from the Loader, and functions to exchange messages between content scripts and the main add-on code from the Worker.

var { Symbiont } = require('sdk/content/content');
var Thing = Symbiont.resolve({ constructor: '_init' }).compose({
  constructor: function Thing(options) {
    // `getMyFrame` returns the host application frame in which
    // the page is loaded.
    this._frame = getMyFrame();
    this._init(options)
  }
});

See the panel module for a real-world example of usage of this module.

Globals

Constructors

Symbiont(options)

Creates a content symbiont.

Parameters

options : object
Optional options:

Name Type  
frame object

The host application frame in which the page is loaded. If frame is not provided hidden one will be created.

contentScriptWhen string

When to load the content scripts. This may take one of the following values:

  • "start": load content scripts immediately after the document element for the page is inserted into the DOM, but before the DOM content itself has been loaded
  • "ready": load content scripts once DOM content has been loaded, corresponding to the DOMContentLoaded event
  • "end": load content scripts once all the content (DOM, JS, CSS, images) for the page has been loaded, at the time the window.onload event fires

This property is optional and defaults to "end".

contentScriptOptions object

Read-only value exposed to content scripts under self.options property.

Any kind of jsonable value (object, array, string, etc.) can be used here. Optional.

allow object

Permissions for the content, with the following keys:

script boolean

Whether or not to execute script in the content. Defaults to true. Optional. Optional.

Symbiont

Symbiont is composed from the Worker trait, therefore instances of Symbiont and their descendants expose all the public properties exposed by Worker along with additional public properties that are listed below:

Properties

contentScriptFile

The local file URLs of content scripts to load. Content scripts specified by this property are loaded before those specified by the contentScript property.

contentScript

The texts of content scripts to load. Content scripts specified by this property are loaded after those specified by the contentScriptFile property.

contentScriptWhen

When to load the content scripts. This may have one of the following values:

  • "start": load content scripts immediately after the document element for the page is inserted into the DOM, but before the DOM content itself has been loaded
  • "ready": load content scripts once DOM content has been loaded, corresponding to the DOMContentLoaded event
  • "end": load content scripts once all the content (DOM, JS, CSS, images) for the page has been loaded, at the time the window.onload event fires

contentScriptOptions

Read-only value exposed to content scripts under self.options property.

Any kind of jsonable value (object, array, string, etc.) can be used here. Optional.

contentURL

The URL of the content loaded.

allow

Permissions for the content, with a single boolean key called script which defaults to true and indicates whether or not to execute scripts in the content.

Revision Source

<div class="note">
 <p>Unstable</p>
</div>
<p><span class="seoSummary">Used by SDK modules that can load web content and attach <a href="dev-guide/guides/content-scripts/index.html">content scripts</a> to it.</span></p>
<h2 id="Usage">Usage</h2>
<p>A <code>Symbiont</code> loads the specified <code>contentURL</code> and content scripts into a frame, and sets up an asynchronous channel between the content scripts and the add-on code, enabling them to exchange messages using the <a href="dev-guide/guides/content-scripts/using-port.html"><code>port</code></a> or <a href="dev-guide/guides/content-scripts/using-postmessage.html"><code>postMessage</code></a> APIs. You map optionally pass a frame into the <code>Symbiont</code>'s constructor: if you don't, then a new hidden frame will be created to host the content.</p>
<p>This trait is composed from the <a href="modules/sdk/content/loader.html"><code>Loader</code></a> and <a href="modules/sdk/content/worker.html"><code>Worker</code></a> traits. It inherits functions to load and configure content scripts from the <code>Loader</code>, and functions to exchange messages between content scripts and the main add-on code from the <code>Worker</code>.</p>
<pre class="brush: js">
var { Symbiont } = require('sdk/content/content');
var Thing = Symbiont.resolve({ constructor: '_init' }).compose({
  constructor: function Thing(options) {
    // `getMyFrame` returns the host application frame in which
    // the page is loaded.
    this._frame = getMyFrame();
    this._init(options)
  }
});</pre>
<p>See the <a href="modules/sdk/panel.html">panel</a> module for a real-world example of usage of this module.</p>
<h2 id="Globals">Globals</h2>
<h3 id="Constructors">Constructors</h3>
<h4 class="addon-sdk-api-name" id="Symbiont(options)"><code>Symbiont(options)</code></h4>
<p>Creates a content symbiont.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>options : object</strong><br />
 Optional options:</p>
<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Name</th>
   <th scope="col">Type</th>
   <th scope="col">&nbsp;</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>frame</td>
   <td>object</td>
   <td>
    <p>The host application frame in which the page is loaded. If frame is not provided hidden one will be created.</p>
   </td>
  </tr>
  <tr>
   <td>contentScriptWhen</td>
   <td>string</td>
   <td>
    <p>When to load the content scripts. This may take one of the following values:</p>
    <ul>
     <li>"start": load content scripts immediately after the document element for the page is inserted into the DOM, but before the DOM content itself has been loaded</li>
     <li>"ready": load content scripts once DOM content has been loaded, corresponding to the <a href="https://developer.mozilla.org/en/Gecko-Specific_DOM_Events">DOMContentLoaded</a> event</li>
     <li>"end": load content scripts once all the content (DOM, JS, CSS, images) for the page has been loaded, at the time the <a href="https://developer.mozilla.org/en/DOM/window.onload">window.onload event</a> fires</li>
    </ul>
    <p>This property is optional and defaults to "end".</p>
   </td>
  </tr>
  <tr>
   <td>contentScriptOptions</td>
   <td>object</td>
   <td>
    <p>Read-only value exposed to content scripts under <code>self.options</code> property.</p>
    <p>Any kind of jsonable value (object, array, string, etc.) can be used here. Optional.</p>
   </td>
  </tr>
  <tr>
   <td>allow</td>
   <td>object</td>
   <td>
    <p>Permissions for the content, with the following keys:</p>
   </td>
  </tr>
  <tr>
   <td>script</td>
   <td>boolean</td>
   <td>
    <p>Whether or not to execute script in the content. Defaults to true. Optional. Optional.</p>
   </td>
  </tr>
 </tbody>
</table>
<h2 id="Symbiont">Symbiont</h2>
<p>Symbiont is composed from the <a href="modules/sdk/content/worker.html">Worker</a> trait, therefore instances of Symbiont and their descendants expose all the public properties exposed by <a href="modules/sdk/content/worker.html">Worker</a> along with additional public properties that are listed below:</p>
<h3 id="Properties">Properties</h3>
<h4 class="addon-sdk-api-name" id="contentScriptFile"><code>contentScriptFile</code></h4>
<p>The local file URLs of content scripts to load. Content scripts specified by this property are loaded <em>before</em> those specified by the <code>contentScript</code> property.</p>
<h4 class="addon-sdk-api-name" id="contentScript"><code>contentScript</code></h4>
<p>The texts of content scripts to load. Content scripts specified by this property are loaded <em>after</em> those specified by the <code>contentScriptFile</code> property.</p>
<h4 class="addon-sdk-api-name" id="contentScriptWhen"><code>contentScriptWhen</code></h4>
<p>When to load the content scripts. This may have one of the following values:</p>
<ul>
 <li>"start": load content scripts immediately after the document element for the page is inserted into the DOM, but before the DOM content itself has been loaded</li>
 <li>"ready": load content scripts once DOM content has been loaded, corresponding to the <a href="https://developer.mozilla.org/en/Gecko-Specific_DOM_Events">DOMContentLoaded</a> event</li>
 <li>"end": load content scripts once all the content (DOM, JS, CSS, images) for the page has been loaded, at the time the <a href="https://developer.mozilla.org/en/DOM/window.onload">window.onload event</a> fires</li>
</ul>
<h4 class="addon-sdk-api-name" id="contentScriptOptions"><code>contentScriptOptions</code></h4>
<p>Read-only value exposed to content scripts under <code>self.options</code> property.</p>
<p>Any kind of jsonable value (object, array, string, etc.) can be used here. Optional.</p>
<h4 class="addon-sdk-api-name" id="contentURL"><code>contentURL</code></h4>
<p>The URL of the content loaded.</p>
<h4 class="addon-sdk-api-name" id="allow"><code>allow</code></h4>
<p>Permissions for the content, with a single boolean key called <code>script</code> which defaults to true and indicates whether or not to execute scripts in the content.</p>
Revert to this revision