Addons developer guide

Getting Started

This guide walks you through the steps needed to make a restartless add-on for Firefox on Android. If you are familiar with building add-ons for desktop Firefox, much of this guide will be review. Firefox on Android uses native Android widgets for the browser UI so the big difference is how you interact with the browser UI.

This add-on won't do anything in particular, just show you how to hook into the new APIs. Building something useful is an exercise left to the reader.

Boilerplate

As always, we need an install.rdf file. There is nothing new here except for the Firefox on Android app-id, but note that we do set the bootstrap flag:

Since we are making a restartless add-on, we also need a bootstrap.js file. This file is the main entry point for the add-on. The requirements for the file are simple, but you need to add some of your own code to make sure you manage DOM windows. Here is a simple example:

This basic code has two window-based entry points: loadIntoWindow and unloadFromWindow. Think of these methods like you would window.onload and window.onunload for non-restartless add-ons. These are the places where we can add our add-on specific UI and behavior. There are many more features and utilities you can use with restartless add-ons.

I also added a helper method, isNativeUI, in case you need to check to see if the add-on is running in Native Firefox on Android or the older XUL-based version.

Adding UI

To add UI widgets in traditional add-ons, you could use XUL overlays or dynamically create XUL elements and add them to the DOM document. You can't do that in Firefox on Android since the UI is entirely native widgets. Instead, you can use an API to manipulate the native UI. The entry point for the API is a JavaScript object called NativeWindow. The API allows you to interact with several UI widgets:

Android Menu

Popup (doorhanger) Notifications

Context Menus (in web content)

Android Toast alerts

Adding/Removing a Menu Item

You can add and remove a menu item from the Android application main menu. When adding a menu, you are given a token which you can use to remove the menu:

Showing a Toast Alert

A toast alert is a simple short lived notification popup. It is useful for showing an action has completed without causing the user too much distraction. The popup closes on its own after a short or long duration.

Showing a Notification

Doorhanger notifications are slightly more complicated, and allow the user to tap buttons to make a choice. The popups are modeless so they don't require the user to explicitly close them. They are assoicated with a tab too, so switching to a different tab will hide any open notifications. Conversely, when switching back to a tab with active doorhanger notifications causes them to become visible again.

If you don't explicitly pass a tab ID along with the doorhanger, the selected tab is assumed. You can also pass a name along with the doorhanger, "doorhanger-test" in this example. You can use the name to hide the doorhanger programmatically, if needed:

Adding/Removing a Context Menu

You can add and remove a menu item from the web content context menu. A context menu appears when you long-tap on an element in the webpage. Firefox already has some built-in context menus, but you can create your won too. When adding a context menu, you are given a token which you can use to remove the context menu:

You can see that a context menu is a bit more complicated than a simple menu. The second parameter is a selector function (think CSS selector) that let's Firefox know what type of element triggers your context menu. In the example I use the built-in link (<a>) selector. The selector is simply an object with a matches method like this:

Showing Dialogs and Prompts

You can show native Android dialogs and prompt using the same nsIPromptService interface used on desktop Firefox. The implementation uses native Android dialogs instead of the XUL dialogs used on desktop.

Wrapping It Up

As with any other restartless add-on, you need to bundle the install.rdf and bootstrap.js (along with any other files you added) into an XPI file. You are now ready to install your add-on and try it out.

Installing addons on Android can be a bit tricky. There are a few different approaches that developers take. If you're comfortable putting your extension up on a public server, you can just follow a link. There are also extensions to simplify the process. If you have the Android SDK installed, you can also run a few simple adb commands to copy the extension to your phone and load it in Fennec: