content/symbiont
The symbiont
module exports the Symbiont
trait, which is used in
the internal implementation of SDK modules, such as
panel
and
page-worker
, that can load web
content and attach
content scripts to it.
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.
API Reference
Classes
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:
Constructors
Symbiont(options)
Creates a content symbiont.
Options for the constructor. Includes all the keys that the Worker constructor accepts and a few more:
The host application frame in which the page is loaded. If frame is not provided hidden one will be created.
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".
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.
Permissions for the content, with the following keys:
Whether or not to execute script in the content. Defaults to true. Optional. Optional.
Properties
contentScriptFile : array
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 : array
The texts of content scripts to load. Content scripts specified by this
property are loaded after those specified by the contentScriptFile
property.
contentScriptWhen : string
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 : 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.
contentURL : string
The URL of the content loaded.
allow : object
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.