Frame script environment

Jump to:

The frame script's global is a ContentFrameMessageManager, giving it the following environment:

content The DOM window of the content loaded in the browser may be null (see below)
docShell The nsIDocShell associated with the browser.
addEventListener() Listen to events from content.
removeEventListener() Stop listening to events from content.
addMessageListener() Listen to messages from chrome.
removeMessageListener() Stop listening to messages from chrome.
sendAsyncMessage() Send an asynchronous message to chrome.
sendSyncMessage() Send a synchronous message to chrome.
dump() Print a message to the console.
atob() Base64 decode.
btoa() Base64 encode.
Components The usual Components object.

In particular, note that a frame script accesses the DOM window using content, not window:

// frame script
var links = content.document.getElementsByTagName("a");

All of the frame scripts running in a tab share this global. However, any top-level variables defined by a script are not stored on the global: instead, top-level variables are stored in a special per-script object that delegates to the per-tab global. This means you don't have to worry about global variables you define conflicting with global variables defined by another frame script. You can still access the global directly using this.

Frame scripts run with system principals. If you want other principals or when interacting with untrusted page scripts, you should use a Sandbox.

Frame scripts run with system privileges and have access to the Components object, enabling them to use XPCOM objects and JSMs. However, some APIs that work in the chrome process do not work in a frame script. See Limitations of frame scripts for more details.


Besides the regular DOM events being captured/bubbling up from content the current content object the following additional events get fired in a frame script environment:


Fires when the frame script environment is shut down, i.e. when a tab gets closed.

If you use a capturing event listener on the ContentFrameMessageManager, you should verify that its is set to the ContentFrameMessageManager global object to avoid handling unload events from content.


Fires when a new content object is created.

This can be used if a framescript needs to interact with individual DOM windows instead of simply listening for events bubbling up from content.
Another use is to interact with the content very early in the page load process, long before DOMContentLoaded event is fired.


Document Tags and Contributors

Contributors to this page: wbamberg, The_8472, rolfedh
Last updated by: wbamberg,