Add-ons using the techniques described in this document are considered a legacy technology in Firefox. Don't use these techniques to develop new add-ons. Use WebExtensions instead. If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions.
From Firefox 53 onwards, no new legacy add-ons will be accepted on addons.mozilla.org (AMO).
From Firefox 57 onwards, WebExtensions will be the only supported extension type, and Firefox will not load other types.
Even before Firefox 57, changes coming up in the Firefox platform will break many legacy extensions. These changes include multiprocess Firefox (e10s), sandboxing, and multiple content processes. Legacy extensions that are affected by these changes should migrate to WebExtensions if they can. See the "Compatibility Milestones" document for more.
A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.
Unstable
Provides one of the building blocks for those modules that use content scripts to interact with web content, such as panel
and page-mod
.
Usage
The module exports a constructor for the Loader
object, which inherits on()
, once()
, and removeListener()
functions that enable its users to listen to events.
Loader
adds code to initialize and validate a set of properties for managing content scripts:
contentURL
contentScript
contentScriptFile
contentScriptWhen
contentScriptOptions
allow
When certain of these properties are set, the Loader
emits a propertyChange
event, enabling its users to take the appropriate action.
The Loader
is used by modules that use content scripts but don't themselves load content, such as page-mod
.
Modules that load their own content, such as panel
and page-worker
, use the symbiont
module instead. Symbiont
inherits from Loader
but contains its own frame into which it loads content supplied as the contentURL
option.
Example:
The following code creates a wrapper on a hidden frame that reloads a web page in the frame every time the contentURL
property is changed:
var hiddenFrames = require("sdk/frame/hidden-frame"); var { Loader } = require("sdk/content/content"); var PageLoader = Loader.compose({ constructor: function PageLoader(options) { options = options || {}; if (options.contentURL) this.contentURL = options.contentURL; this.on('propertyChange', this._onChange = this._onChange.bind(this)); let self = this; hiddenFrames.add(hiddenFrames.HiddenFrame({ onReady: function onReady() { let frame = self._frame = this.element; self._emit('propertyChange', { contentURL: self.contentURL }); } })); }, _onChange: function _onChange(e) { if ('contentURL' in e) this._frame.setAttribute('src', this._contentURL); } });
Loader
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 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
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 the following keys: