We are planning to deprecate the use by Firefox add-ons of the techniques described in this document.
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 instead.
Add-ons developed using these techniques might not work with multiprocess Firefox (e10s), which is already the default in Firefox Nightly and Firefox Developer Edition, and will soon be the default in Beta and Release versions of Firefox. We have documentation on making your add-ons multiprocess-compatible, but it will be more future-proof for you to migrate to WebExtensions.
A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.
This page is now obsolete, and its content has been incorporated into the main page on content scripts.
The constructors for content-script-using objects such as panel and page-mod define a group of options for loading content scripts:
contentScript string, array contentScriptFile string, array contentScriptWhen string contentScriptOptions object
We have already seen the
contentScript option, which enables you to pass in the text of the script itself as a string literal. This version of the API avoids the need to maintain a separate file for the content script.
contentScriptFile option enables you to pass in the local file URL from which the content script will be loaded. To supply the file "my-content-script.js", located in the /data subdirectory under your add-on's root directory, use a line like:
// "data" is supplied by the "self" module var data = require("sdk/self").data; ... contentScriptFile: data.url("my-content-script.js")
contentScriptFile accept an array of strings, so you can load multiple scripts, which can also interact directly with each other in the content process:
// "data" is supplied by the "self" module var data = require("sdk/self").data; ... contentScriptFile: [data.url("jquery-1.4.2.min.js"), data.url("my-content-script.js")]
Unless your content script is extremely simple and consists only of a static string, don't use
contentScript: if you do, you may have problems getting your add-on approved on AMO.
Instead, keep the script in a separate file and load it using
contentScriptFile. This makes your code easier to maintain, secure, debug and review.
contentScriptWhen option specifies when the content script(s) should be loaded. It takes one of three possible values:
"start" loads the scripts immediately after the document element for the page is inserted into the DOM. At this point the DOM content hasn't been loaded yet, so the script won't be able to interact with it.
"ready" loads the scripts after the DOM for the page has been loaded: that is, at the point the DOMContentLoaded event fires. At this point, content scripts are able to interact with the DOM content, but externally-referenced stylesheets and images may not have finished loading.
"end" loads the scripts after all content (DOM, JS, CSS, images) for the page has been loaded, at the time the window.onload event fires.
The default value is "end".
contentScriptOptions is a json that is exposed to content scripts as a read only value under
Any kind of jsonable value (object, array, string, etc.) can be used here.