Please note, this is a STATIC archive of website developer.mozilla.org from 03 Nov 2016, cach3.com does not collect or store any user information, there is no "phishing" involved.
Add-ons

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. Requires Gecko 41

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 GRID view types. Header images are positioned at the top of the page and extend across the entire page width.

The header object contains two properties:

  • image_url: URL pointing to the image to display in the header
  • url: URL to open when the header image is clicked.

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 = "[email protected]";
const DATASET_ID = "[email protected]";

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:

Document Tags and Contributors

Tags: 
 Contributors to this page: wbamberg, rolfedh, dkocho4, skaspari, leibovic, freaktechnik, jdover
 Last updated by: wbamberg,