Update: the SDK 1.2 beta builds ( including this one, just released today ) now include a more refined version of this content. If you’re interested in this material I strongly suggest that you download this beta and take a look at the bundled docs.
This post is an attempt to clearly explain how content scripts work. I am posting this particular topic as a blog post in hopes of getting feedback on the wording, but the content below is actually part of a larger patch against the SDK documentation that Will Bamberg created as part of this SDK bug. The specific purpose of this post is to explain the access that content scripts have to:
- DOM objects in the pages they are attached to
- other content scripts
- other scripts loaded by the page they are attached to
Access to the DOM
Content scripts need to be able to access DOM objects in arbitrary web pages, but this gives rise to a potential security problem. A malicious page could redefine standard functions and properties of DOM objects so they don’t do what the add-on expects. To deal with this, content scripts access DOM objects via a proxy. Any changes they make are made to the proxy.
The proxy is based on XRayWrapper
, (also known as XPCNativeWrapper
). These wrappers give the user access to the native values of DOM functions and properties, even if they have been redefined by a script.
For example: the page below redefines window.confirm()
to return true
without showing a confirmation dialog:
Thanks to the content proxy, a content script which calls window.confirm()
will get the native implementation:
var widgets = require("widget");
var tabs = require("tabs");
var data = require("self").data;
var widget = widgets.Widget({
id: "transfer",
label: "Transfer",
content: "Transfer",
width: 100,
onClick: function() {
tabs.activeTab.attach({
// native implementation of window.confirm will be used
contentScript: "console.log(window.confirm('Transfer all my money?'));"
});
}
});
tabs.open(data.url("xray.html"));
You can try this example at: https://builder.addons.mozilla.org/addon/1013777/revision/4/.
The proxy is transparent to content scripts. As far as the content script is concerned, it is accessing the DOM directly, however because it is not, some things that you might expect to work, won’t. For example, if the page includes a library like jQuery, or any other page script adds any other objects to the window, they won’t be visible to the content script. So to use jQuery you’ll typically have to add it as a content script, as in this example.
unsafeWindow
If you really need direct access to the underlying DOM, you can use the global unsafeWindow
object. Try editing the example at https://builder.addons.mozilla.org/addon/1013777/revision/4/ so the content script uses unsafeWindow.confirm()
instead of window.confirm()
to see the difference.
Avoid using unsafeWindow
if possible! It is the same concept as Greasemonkey’s unsafeWindow, and the warnings for that apply equally here. Also, unsafeWindow
isn’t a supported API, so it could be removed or changed in a future version of the SDK.
Access to Other Content Scripts
If you load several content scripts loaded into the same document can interact with each other directly as well as with the web content itself. This allows you to do things like load jQuery and then load your own scripts that use jQuery. Content scripts which have been loaded into different document cannot interact with each other.
For example:
- if an add-on creates a single
panel
object and loads several content scripts into the panel, then they can interact with each other. - if an add-on creates two
panel
objects and loads a script into each one, they cannot interact with each other. - if an add-on creates a single
page-mod
object and loads several content scripts into the page mod, then only content scripts associated with the same page can interact with each other: if two different matching pages are loaded, content scripts attached to page A cannot interact with those attached to page B.
The web content has no access to objects created by the content script, unless the content script explicitly makes them available. For example, you could expose a variable in your content script directly to web content by doing something like this:
Access to Page Scripts
You can communicate between the content script and page scripts using postMessage()
, but there’s a twist: in early versions of the SDK, the global postMessage()
function in content scripts was used for communicating between the content script and the main add-on code. Although this has been deprecated in favor of self.postMessage
, the old globals are still supported, so you can’t currently usewindow.postMessage()
. You must use document.defaultView.postMessage()
instead.
The following page script uses window.addEventListener
to listen for messages:
Content scripts can send it messages using document.defaultView.postMessage()
:
var widgets = require("widget");
var tabs = require("tabs");
var data = require("self").data;
var widget = widgets.Widget({
id: "postMessage",
label: "demonstrate document.defaultView.postMessage",
contentURL: "http://www.mozilla.org/favicon.ico",
onClick: function() {
tabs.activeTab.attach({
contentScript: "document.defaultView.postMessage('hi there!', '*');"
});
}
});
tabs.open(data.url("listener.html"));
You can see this add-on at https://builder.addons.mozilla.org/addon/1013849/revision/8/.
Derrick Rice (:drice) wrote on
Jeff Griffiths wrote on
Derrick Rice (:drice) wrote on
John Nagle wrote on
Jeff Griffiths wrote on
John Nagle wrote on
John Nagle wrote on
John Nagle wrote on
Jeff Griffiths wrote on
John Nagle wrote on
Jeff Griffiths wrote on
John Nagle wrote on
Jeff Griffiths wrote on