Firefox Hub Walkthrough

This guide walks you through developing a Firefox Hub add-on for Firefox for Android. The Firefox Hub APIs allow add-ons to add new content to the Firefox for Android home page. These APIs are new in Firefox 30, and increased capabilities are planned for future releases. The two main APIs that this guide covers are the Home.panels API and the HomeProvider API. For some example code to get started, you can copy the hub boilerplate add-on from github.

This guide assumes you understand the basics of building a restartless add-on for Firefox for Android. Please see the basic Firefox for Android add-on Walkthrough guide for more information about getting started.

Overview

There are two main parts to building a Firefox Hub add-on: creating a home panel, and storing data to show in that panel. Home panels consist of different views, each of which displays data from a given dataset.

Creating a home panel

To create a home panel, first use the Home.panels API to register a panel. The register API takes a panel id and an options callback function as parameters. This options callback is called to dynamically generate an options object whenever a panel is installed or updated, which allows for dynamic locale changes.

Cu.import("resource://gre/modules/Home.jsm");

const PANEL_ID = "[email protected]";
const DATASET_ID = "[email protected]";

function panelOptionsCallback() {
  return {
    title: "My Panel",
    views: [{
      type: Home.panels.View.LIST,
      dataset: DATASET_ID
    }]
  };
}

Home.panels.register(PANEL_ID, panelOptionsCallback);

You must always register your panel on startup, but when your add-on is installed (or whenever you want to actually add the panel to the user's home page), you must also install it.

Home.panels.install(PANEL_ID);

See the Home.panels API documentation for details about how to add more features to your panels, such as authentication and empty views. You can also register to listen for user actions, such as installing or refreshing a panel.

Storing data

Use the HomeProvider API to store data to display in your home panel. The HomeProvider API gives you access to HomeStorage objects, which allow you to asynchronously save and delete data for a given dataset. The save and deleteAll APIs return promises that are resolved when the transaction is complete. You can use Task.jsm to execute these transactions within a task.

Cu.import("resource://gre/modules/HomeProvider.jsm");
Cu.import("resource://gre/modules/Task.jsm");

let items = [
 { url: "https://example.com/1", title: "Example 1" },
 { url: "https://example.com/2", title: "Example 2" }
];

let storage = HomeProvider.getStorage(DATASET_ID);
Task.spawn(function() {
  // Delete any existing items.
  yield storage.deleteAll();
  // Save the new items.
  yield storage.save(items);

  // New way to replace items in Firefox 31+
  // yield storage.save(items, { replace: true });
}).then(null, Cu.reportError);

In practice, if you are going to use a network request to fetch your data, you should use the requestSync API to allow HomeProvider to decide if it's a good time to sync.

function syncCallback() {
  // Fetch new data and use HomeProvider APIs to store data.
}

HomeProvider.requestSync(DATASET_ID, syncCallback);

You can also use the addPeriodicSync API to request data syncing at a regular interval.

// Calls syncData callback once every 3600 seconds (1 hour)
HomeProvider.addPeriodicSync(DATASET_ID, 3600, syncCallback);

Best practices

Here are some tips for developing hub add-ons:

Use unique ids for panels and datasets.
Register panels in your add-on's startup() function.
Unregister panels in your add-on's shutdown() function.
Delete panel data when a panel is uninstalled.

Example add-ons

Here are some open source add-ons that use these hub APIs: