New Add-on SDK Australis UI features in Firefox 29

Update: the ability to attach a panel to a button, and the ability to include buttons in toolbars, are not included in Firefox 29 (the current Beta release). Both these features are in Firefox 30 (the current Aurora release). Note that it is still possible to add frames to toolbars in Firefox 29.

With Australis entering Beta, I’m pleased to introduce four new APIs for building your add-on’s user interface: the action button, the toggle button, the toolbar, and the frame.

Buttons, buttons everywhere

First up, we have two APIs for adding buttons to Firefox: action buttons and toggle buttons.

You give action buttons an icon, a label, and a click handler:

var ui = require("sdk/ui");

var action_button = ui.ActionButton({
  id: "my-button",
  label: "Action Button!",
  icon: "./icon.png",
  onClick: function(state) {
    console.log("You clicked '" + state.label + "'");
  }
});

Unless you add them to a toolbar of your own, they appear in the toolbar at the top right of the browser window:

Toggle buttons are just the same, except they’re meant to represent an on/off state, like a checkbox. So they have a “checked” property which is toggled when the user clicks the button, and the icon gets a “pressed” look when the button is checked:

var ui = require("sdk/ui");

var toggle_button = ui.ToggleButton({
  id: "my-button",
  label: "my button",
  icon: "./icon.png",
  onChange: function(state) {
    console.log(state.label + " checked state: " + state.checked);
  }
});

You can also attach panels to toggle buttons, by passing the button into the panel’s constructor or its show() method.

Toolbars and frames

The toolbar API lets you create more complex persistent user interfaces. You can add buttons to a toolbar, and can also add frames, which are essentially iframes with message passing between page scripts and your main add-on code. You create a frame by specifying the local HTML content to load into it.

Here’s an example that defines a toolbar with a single frame and three action buttons:

var ui = require('sdk/ui');

var previous = ui.ActionButton({
  id: "previous",
  label: "previous",
  icon: "./icons/16-back.png"
});

var next = ui.ActionButton({
  id: "next",
  label: "next",
  icon: "./icons/16-next.png"
});

var play = ui.ActionButton({
  id: "play",
  label: "play",
  icon: "./icons/16-play.png"
});

var frame = ui.Frame({
  url: "./frame-player.html"
});

var toolbar = ui.Toolbar({
  title: "Player",
  items: [previous, next, play, frame]
});

Toolbars occupy a complete strip of the browser window, just above the content window:

Learning more

There’s full reference documentation on all these APIs on MDN, and I’ve created an example add-on to check out.