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;");' +
'}'
});
}
});
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.