ui/frame

Add-ons using the techniques described in this document are considered a legacy technology in Firefox. Don't use these techniques to develop new add-ons. Use WebExtensions instead. If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions.

Starting from Firefox 53, no new legacy add-ons will be accepted on addons.mozilla.org (AMO) for desktop Firefox and Firefox for Android.

Starting from Firefox 57, only extensions developed using WebExtensions APIs will be supported on Desktop Firefox and Firefox for Android.

Even before Firefox 57, changes coming up in the Firefox platform will break many legacy extensions. These changes include multiprocess Firefox (e10s), sandboxing, and multiple content processes. Legacy extensions that are affected by these changes should migrate to use WebExtensions APIs if they can. See the "Compatibility Milestones" document for more information.

Create HTML iframes, using bundled HTML, CSS and JavaScript, that can be added to a designated area of the Firefox user interface. At the moment you can only add frames to a toolbar.

Usage

This module exports the Frame constructor, which can be used to create frame components. Right now it can be used in conjunction with a Toolbar: you create a Frame, then supply it to the Toolbar's constructor, and the content is then displayed inside the toolbar.

Constructing frames

The Frame constructor takes one mandatory option, which is a url pointing to an HTML document supplied under your add-ons "data" directory.

For example, this HTML document defines a <select> element and a couple of <span> elements, and includes a CSS file to style the content and a JavaScript script to implement behavior:

The toolbar is positioned between the address bar and the content window. It occupies the whole width of the browser window and is 18 pixels high on a normal-resolution display or 36 pixels high on a high-resolution (HiDPI) display. This toolbar might look something like:

Scripting frames

To add scripts to frames, include them directly from the frame's HTML content, as with a normal web page:

<script type="text/javascript" src="frame.js"></script>

As usual, the path to the script is relative to the HTML file's location.

Messages logged from a frame script using the console will not appear in the terminal when you run the add-on using jpm run. However, they will appear in the Browser Console. This issue is being tracked as bug 982385.

Communicating with frames

You can exchange messages between the main add-on code and scripts loaded into the frame using an API modeled on window.postMessage(). A frame creates a separate iframe instance for each browser window. So there are three cases to consider:

sending messages from a frame script to the main add-on code

sending messages from the main add-on code to all instances of a frame, across all browser windows

sending messages from the main add-on code to a single instance of a frame, attached to a specific browser window

In all cases, postMessage() takes two arguments: the message itself and a targetOrigin. The targetOrigin argument can be either the URI of the document hosted by the target, or the wildcard "*". If you use the URI, then the message will only be dispatched to the window whose document matches that URI.

If you know the target URI, you should use it, as this is more secure: it prevents another window from intercepting messages that were intended for someone else.

From frame to add-on

To send a message from a frame script to the add-on, use window.parent.postMessage(). This takes two arguments, the message itself and a target origin.

If the frame script initiates the conversation, you need to specify "*" as the origin:

window.parent.postMessage("ping", "*");

If the frame script has received a message from the add-on already, it can use the origin property of the event object passed to the message hander:

From add-on to all frames

To send a message from the add-on code to all frames, attached to all open browser windows, you can use Frame.postMessage(). You can specify the frame's url property as the targetOrigin:

frame.postMessage(message, frame.url);

This add-on listens for a frame script to send the "city changed" message above, and in response, updates all frames across all browser windows with that city's current weather (it just reads this from a dictionary, where in a real case it might ask a web service):

From add-on to a specific frame

You can send a message from the main add-on code to the frame hosted by a particular browser window. In this way you can customize the frame for each browser window. To do this, you call postMessage() not on the Frame itself but on the source attribute of the object passed into an event listener.

For targetOrigin, you can use the origin property of the event object passed to the message listener:

This is used to generate an ID to to keep track of the frame. If you don't supply a name, the ID is derived from the frame's URL, meaning that if you don't supply a name, you may not create two frames with the same URL.

Parameters

listener : function
The listener function. This is passed an event object which always contains a source property, which has a postMessage() function modeled after window.postMessage(). You can use this to communicate only with the specific frame instance that generated the event, and not to any frame instance attached to other browser windows.

once(event, listener)

Assign a listener to the first occurrence only of an event emitted by the frame. Frame supports the following events: attach, detach, load, ready, and message. The listener is automatically removed after the first time the event is emitted.

Parameters

listener : function
The listener function. This is passed an event object which always contains a source property, which has a postMessage() function modeled after window.postMessage(). You can use this to communicate only with the specific frame instance that generated the event, and not to any frame instance attached to other browser windows.

removeListener(event, listener)

Removes an event listener. For example, this code is equivalent to once():

Parameters

destroy()

Destroy the frame. After calling this function, the frame will no longer appear in the UI, and accessing any of its properties or methods will throw an error.

Properties

url

URL for the content loaded into the frame. This is read-only. It's only accessible after the attach event has occurred for this frame.

Events

attach

This event is emitted whenever a new frame instance is constructed and the browser has started to load its document: for example, when the user opens a new browser window, if that window has a toolbar containing this frame. Since the event is dispatched asynchronously, the document may already be loaded by the time the event is received.

At this point, you should not try to send messages to scripts hosted in the frame, because the frame scripts may not have been loaded.

Arguments

event : This contains two properties:

source, which defines a postMessage() function which you can use to send messages back to this particular frame instance. But note that at this point you should not try to send messages to scripts hosted in the frame, because the frame scripts may not have been loaded.

origin, which you can use as the targetOrigin argument to postMessage() if you want to communicate with this particular frame instance.

detach

This event is emitted when a frame instance is unloaded: for example, when the user closes a browser window, if that window has a toolbar containing this frame. After receiving this message, you ahould not attempt to communicate with the frame scripts.

ready

This event is emitted while a frame instance is being loaded, at the point where it becomes possible to interact with the frame although sub-resources may still be in the process of loading. It's the equivalent of the point where the frame's document.readyState becomes "interactive":