gistfile1.md

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 button an icon, a label, and a click handler:

var { ActionButton } = require("sdk/ui/button/action");

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

It appears in the toolbar at the top right of the browser window:

screenshot goes here

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

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 get a "pressed" look when the button is checked.

var { ToggleButton } = require("sdk/ui/button/toggle");

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

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 SDK-style 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 an action button:

var { ActionButton } = require("sdk/ui/button/action");
var { Frame } = require("sdk/ui/frame");
var { Toolbar } = require("sdk/ui/toolbar");

var toolbar_button = ActionButton({
  id: "toolbar-button",
  label: "Show Toolbar",
  icon: "./check_mark.png",
  onClick: function(state) {
    console.log('Clicked the toolbar button!');
  }
});

var frame = new Frame({
  url: "./frame.html"
});

var toolbar = Toolbar({
  title: "Test-addon",
  items: [toolbar_button, frame]
});

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

screenshot goes here

Learn more

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