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.
From Firefox 53 onwards, no new legacy add-ons will be accepted on addons.mozilla.org (AMO).
From Firefox 57 onwards, WebExtensions will be the only supported extension type, and Firefox will not load other 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.
A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.
To follow this tutorial you'll need to have learned the basics of jpm.
To add a button to the toolbar, use the action button or toggle button modules.
Create a new directory, navigate to it, and execute jpm init, accepting all the defaults.
Create a directory called "data",
mkdir data
and save these three icon files to the "data" directory:
 |
icon-16.png |
 |
icon-32.png |
 |
icon-64.png |
Then open the file called "index.js" in the root of your addon directory and add the following code to it:
var buttons = require('sdk/ui/button/action');
var tabs = require("sdk/tabs");
var button = buttons.ActionButton({
id: "mozilla-link",
label: "Visit Mozilla",
icon: {
"16": "./icon-16.png",
"32": "./icon-32.png",
"64": "./icon-64.png"
},
onClick: handleClick
});
function handleClick(state) {
tabs.open("https://www.mozilla.org/");
}
Now run the add-on with jpm run. The button is added to the toolbar at the top of the browser window:
You can't set the initial location for the button, but the user can move it using the browser's customization feature. The id attribute is mandatory, and is used to remember the position of the button, so you should not change it in subsequent versions of the add-on.
Clicking the button loads https://www.mozilla.org/ into a new tab.
Specifying the icon
The icon property may specify a single icon or a collection of icons in different sizes, as in the example above. If you specify a collection of icons in different sizes the browser will automatically choose the best fit for the screen resolution and the place in the browser UI that hosts the button. Read more about specifying multiple icons.
The icon file must be packaged with your add-on: it may not refer to a remote file.
You can change the icon at any time by setting the button's icon property. You can change the icon, and the other state attributes, either globally, for a specific window, or for a specific tab. Read more about updating state.
Attaching a panel
If you need to attach a panel to a button, use the toggle button API. This is just like the action button API except it adds a boolean checked property which is toggled whenever the button is checked. To attach the panel, pass the button to the panel's show() method. For more details on this, see the toggle button's documentation.
Displaying richer content
To create more complex user interface content than is possible with just a button, use the toolbar API. With the toolbar API you get a complete horizontal strip of user interface real estate. You can add buttons to the toolbar and also frames, that can host HTML, CSS, and JavaScript.