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, WebExtensions will be the only supported extension type. Desktop Firefox and Firefox for Android will not load other extension types.
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 WebExtensions if they can. See the "Compatibility Milestones" document for more information.
A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.
Summary
Use the Home.panels API to add custom panels to the browser's home page.
Method Overview
void register(in string id, in function optionsCallback) |
void unregister(in string id) |
void install(in string id) |
void uninstall(in string id) |
void update(in string id) |
void setAuthenticated(in string id, in boolean isAuthenticated) |
Constants
Layout types
| Constant | Description |
Layout.FRAME |
A single view that appears as the content of the panel. The default (and only supported) panel layout. |
View types
| Constant | Description |
View.LIST |
Display items in a list. |
View.GRID |
Display items in a grid. |
Item types
| Constant | Description |
Item.ARTICLE |
Title and description of are the focus of the item. The default article for View.LIST views. |
Item.IMAGE |
A large image is the focus of the item. The default image for View.GRID views. |
Item.ICON |
Experimental: an icon (optional), a title (optional), a background image or a background color are the focus of the item. Used in conjunction with View.GRID to build "speed dial" panels. |
ItemHandler types
| Constant | Description |
ItemHandler.BROWSER |
Item URL opens in the browser. The default URL for all views. |
ItemHandler.INTENT |
Item URL launches an Android intent. |
Panel options
When registering a panel, you must pass in an optionsCallback function that returns an object with these attributes.
| Attribute | Type | Required | Description |
title |
string |
yes | Title for the panel. |
layout |
Layout |
no | Specifies the way views are presented in a panel. |
views |
array |
yes | The views to display in a panel. |
oninstall |
function |
no | Callback function called when panel is installed. |
onuninstall |
function |
no | Callback function called when panel is uninstalled. |
auth |
object |
no | Specifies authentication UI. |
View options
Attributes that can be specified by objects in the views array.
| Attribute | Type | Required | Description |
type |
View |
yes | Specifies the way the view displays items. |
dataset |
string |
yes | Unique ID of the dataset the view displays. |
backImageUrl |
string |
no | Image to display as "back" button when a filter is applied. |
itemType |
Item |
no | Specifies the layout of individual items. |
itemHandler |
ItemHandler |
no | Specifies action for item URLs. |
empty |
object |
no | Specifies UI to show when there is no data available. If this is not specified, a default image and text appears in the view. |
onrefresh |
function |
no | Callback for pull-to-refresh to update dataset. save() must be called on the HomeStorage for this dataset to end refresh animation. If no callback is specified, pull-to-refresh is disabled for this view. |
header |
object |
no |
New in Firefox 42. The object that specifies a header image for The
|
Auth options
Attributes that can be specified in a panel's auth object.
| Attribute | Type | Required | Description |
authenticate |
function |
yes | Callback that is called when the user clicks a button to try to authenticate. |
messageText |
string |
yes | Text to display above authentication button. |
buttonText |
string |
yes | Text to display in authentication button. |
imageUrl |
string |
no | Image to display above authentication text. |
Empty view options
Attributes that can be specified in a view's empty object.
| Attribute | Type | Required | Description |
text |
string |
no | Text to display in empty view. |
imageUrl |
string |
no | Image to display above text. This image is displayed in a 90dp square (90px on mdpi devices, 180px on xhdpi devices). |
Methods
register()
Registers a panel. An installed panel must always be registered during startup. This method does not add a panel to about:home.
void register( in string id, in function optionsCallback )
Parameters
- id
- A unique id for this add-on.
- optionsCallback
- A function that returns an options object for this panel.
unregister()
Unregisters a panel.
void unregister( in string id )
Parameters
- id
- A unique id for this add-on.
install()
Adds a panel to the set of active panels on about:home.
void install( in string id )
Parameters
- id
- A unique id for this add-on.
uninstall()
Removes a panel from the set of active panels on about:home.
void uninstall( in string id )
Parameters
- id
- A unique id for this add-on.
update()
Updates a panel. It does so by re-running the options callback from the panel registration.
void update( in string id )
Parameters
- id
- A unique id for this add-on.
setAuthenticated()
Sets the authentication state of a panel.
void setAuthenticated( in string id, in boolean isAuthenticatd )
Parameters
- id
- A unique id for this add-on.
- boolean
- Whether or not the panel is authenticated.
Example
const PANEL_ID = "test.panel@mydomain.com";
const DATASET_ID = "test.dataset@mydomain.com";
function optionsCallback() {
return {
title: "My Panel",
views: [{
type: Home.panels.View.LIST,
dataset: DATASET_ID,
// optional, only used if there's a filter applied after clicking on an item
backImageUrl: "myBackIcon.png",
// optional, defaults to BROWSER (can also specify INTENT to launch an intent)
itemHandler: Home.panels.ItemHandler.BROWSER
}],
// optional, defaults to FRAME (only supported layout for v1)
layout: Home.panels.Layout.FRAME,
// optional, used to show authentication UI (added in Firefox 32)
auth: {
authenticate: function authenticate() {
// do some stuff to authenticate the user
Home.panels.setAuthenticated(PANEL_ID, true);
},
messageText: "Please log in to this panel",
buttonText: "Log in"
}
};
}
Home.panels.register(PANEL_ID, optionsCallback);
Home.panels.install(PANEL_ID);
See also
Some demo add-ons are available on Github: