Frame script environment

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 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 via this.

Frame scripts run with system principals. If you want other principals, you can 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 will not work in a frame script. See Limitations of frame scripts for more details.

Events

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:

unload

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 event.target is set to the ContentFrameMessageManager global object in order to avoid handling unload events from content.

Does not bubble.

DOMWindowCreated

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, mnoorenberghe, The_8472, Changbin, cpeterson
 Last updated by: wbamberg,