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.
* The content script "element-getter.js" is attached to the document
and runs. It adds a listener to the `getElements` message.
* The `attach` event is sent to the "main.js" code. Its event handler sends
the `getElements` message to the content script, and then adds a listener
to the `gotElement` message.
* The content script receives the `getElements` message, retrieves all
elements of that type, and for each element sends a `gotElement` message
containing the element's `innerHTML`.
* The "main.js" code receives each `gotElement` message and logs the
contents.
If multiple documents that match the page-mod's `include` pattern are loaded,
then each document is loaded into its own execution context with its own copy
of the content scripts. In this case the listener assigned to `onAttach`
is called once for each loaded document, and the add-on code will have a
separate worker for each document.
To learn much more about communicating with content scripts, see the
[guide to content scripts](dev-guide/guides/content-scripts/index.html) and in
particular the chapter on
[communicating using `port`](dev-guide/guides/content-scripts/using-port.html).
## Mapping Workers to Tabs ##
The `worker` has a `tab` property which returns the tab associated with
this worker. You can use this to access
the [`tabs API`](modules/sdk/tabs.html) for the tab associated
with a specific document:
var pageMod = require("sdk/page-mod");
var tabs = require("sdk/tabs");
pageMod.PageMod({
include: ["*"],
onAttach: function onAttach(worker) {
console.log(worker.tab.title);
}
});
## Destroying Workers ##
Workers generate a `detach` event when their associated document is closed:
that is, when the tab is closed or the tab's location changes. If
you are maintaining a list of workers belonging to a page-mod, you can use
this event to remove workers that are no longer valid.
For example, if you maintain a list of workers attached to a page-mod:
var workers = [];
var pageMod = require("sdk/page-mod").PageMod({
include: ['*'],
contentScriptWhen: 'ready',
contentScriptFile: data.url('pagemod.js'),
onAttach: function(worker) {
workers.push(worker);
}
});
You can remove workers when they are no longer valid by listening to `detach`:
var workers = [];
function detachWorker(worker, workerArray) {
var index = workerArray.indexOf(worker);
if(index != -1) {
workerArray.splice(index, 1);
}
}
var pageMod = require("sdk/page-mod").PageMod({
include: ['*'],
contentScriptWhen: 'ready',
contentScriptFile: data.url('pagemod.js'),
onAttach: function(worker) {
workers.push(worker);
worker.on('detach', function () {
detachWorker(this, workers);
});
}
});
## Attaching Content Scripts to Tabs ##
We've seen that the page-mod API attaches content scripts to documents based
on their URL. Sometimes, though, we don't care about the URL: we just want
to execute a script on demand in the context of a particular tab.
For example, we might want to run a script in the context of the currently
active tab when the user clicks a widget: to block certain content, to
change the font style, or to display the document's DOM structure.
Using the `attach` method of the [`tab`](modules/sdk/tabs.html)
object, you can attach a set of content scripts to a particular tab. The
scripts are executed immediately.
The following add-on creates a widget which, when clicked, highlights all the
`div` elements in the document loaded into the active tab:
var widgets = require("sdk/widget");
var tabs = require("sdk/tabs");
var widget = widgets.Widget({
id: "div-show",
label: "Show divs",
contentURL: "http://www.mozilla.org/favicon.ico",
onClick: function() {
tabs.activeTab.attach({
contentScript:
'var divs = document.getElementsByTagName("div");' +
'for (var i = 0; i < divs.length; ++i) {' +
'divs[i].setAttribute("style", "border: solid red 1px;");' +
'}'
});
}
});
## Private Windows ##
If your add-on has not opted into private browsing, then your page-mods will
not attach content scripts to documents loaded into private windows, even if
their URLs match the pattern you have specified.
To learn more about private windows, how to opt into private browsing, and how
to support private browsing, refer to the
[documentation for the `private-browsing` module](modules/sdk/private-browsing.html).
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.