Australis and add-on compatibility

Changes for extensions

We've removed the add-ons toolbar (including the status-bar). You should no longer rely on it existing. There is a shim in place that will attempt to migrate your icons, but it may not work, or only work partially. The best solution is to change the placement of your button. This may also be a good time to wonder if your add-on really needs a toolbar button to be visible by default for all users. Add-ons made using the Add-on SDK should not need to worry about this change.

We've removed the application (Firefox) menu. Instead, there is a new panel-based menu that can be opened with a button on the far side of the navigation toolbar. Toolbar items can be dragged in and out from this panel.

Some of the default toolbarbutton IDs have changed, we have added some new ones, and the sequence of back/forward button, URL bar, stop/reload button, will no longer be customizable. This also means users cannot add new (add-on-provided) buttons inbetween these items using the normal customization flow.

The standalone stop reload buttons have been removed.

We're changing the way toolbar buttons are added. While we've attempted to maintain some measure of backward compatibility, the following are deprecated and will be removed in the near future: the toolbar.insertItem method, the toolbar.currentSet property, and the currentset attribute on toolbars. If possible, please stop relying on them. Instead, you should use the CustomizableUI module.

CustomizableUI introduces a new API to insert, move and remove toolbar buttons and other toolbar items, as well as creating panels that are anchored to these toolbarbuttons. We believe this will be simpler and more powerful than the previous mix of APIs.

Because of the new customization APIs, your toolbar buttons may not be direct children of a XUL <toolbar>; they might still be in a toolbar, or they might be in the "customization target" of a toolbar (a descendant node in a toolbar), or they might be in the new menu panel. The customization target of any toolbar (whether the target is a child node, or the toolbar itself) via toolbar.customizationTarget.

Icon sizes in toolbars have changed, and you should ideally provide a larger icon for your add-on's buttons, should they exist, for use in the menu panel and customization area (palette). The new icon sizes are the same on all platforms and are:

  • Toolbars:
    16px (32px @2dppx) without padding.
    Internal icons on the navbar use 18px. For add-ons, by default the padding is set up so it should work well if add-ons specify an icon of size 16px.
  • Menu panel/Customization area (palette):
    32px (64px @2dppx)
    Please note that smaller icons will be upscaled.

When in the customization area (palette), the button will be wrapped in a toolbarpaletteitem with a place attribute set to palette. Putting it all together, your updated CSS might look like this:

#my-addon-button {
    list-style-image: url(icon16.png);
}
#my-addon-button[cui-areatype="menu-panel"],
toolbarpaletteitem[place="palette"] > #my-addon-button {
    list-style-image: url(icon32.png);
}
/* High-resolution displays */
@media (min-resolution: 2dppx) {
    #my-addon-button {
        list-style-image: url(icon32.png);
    }
    #my-addon-button[cui-areatype="menu-panel"],
    toolbarpaletteitem[place="palette"] > #my-addon-button {
        list-style-image: url(icon64.png);
    }
}

Tab markup and styling have changed. If your add-on affects the tabstrip or provides alternative visualizations of the tabstrip, changes tab colors, or anything else related to the tabstrip, you may want to verify that it still works.

The navigation toolbar is always visible (except in popup windows where a reduced navigation toolbar with the urlbar is visible) and can no longer be hidden e.g. for update pages or in-content UI. The related Add-on SDK module addon-page has been removed as it no longer has any effect.

Items in the navigation toolbar can be overflowed if the browser window is made too small. Items in the toolbar will be moved into the new "overflow panel" when this occurs. The overflow panel is anchored to a button that appears in the navigation toolbar when one or more items are overflowed. If your item should never be overflowed, set an overflows attribute to false on the item. The urlbar-container is not overflowable by default, for example. Items that are overflowed have the overflowedItem attribute set to true.

The menu panel uses a 3-column grid layout. Items should either fit in a single grid column (toolbarbuttons will be styled to do so automatically) or span the entire width of the panel if they wouldn't fit in a single grid column, e.g. for wide toolbaritems. In order to have the latter work correctly, you should use the panel-wide-item class on your toolbaritem.

If your add-on provides a <toolbarbutton type="menu"/> or <toolbarbutton type="menu-button"/>, consider moving to a subview-based design, which will work much better in the menu panel. There's some documentation you can look at, as well as the implementation of the history widget.

If your add-on provides a simple toolbarbutton then it should automatically be styled correctly in the menu panel, overflow panel and palette. If it provides a toolbaritem it is likely you will need to do additional work to make it look nice in places other than a toolbar.

All items will have context menus allowing users to move the items between the palette, panel and the navigation toolbar. If your add-on uses the contextmenu itself, we will not override or change it (see this bug for a lengthy discussion as to why). You are requested, however, to update your menus yourself so that users do have the possibility of using these options even for your add-on's button.

The class attribute on tab close buttons has been changed. Extensions shouldn't be relying on the class attribute value since it is a list of tokens and should instead look for the anonid attribute with value "close-button".

The close-icon class now works cross-platform to provide a close icon with a default, hover, and active state. Previously, this wasn't available on Linux and the GTK close icon (gtk-close) was used instead.

The BrowserToolboxCustomizeDone, BrowserToolboxCustomizeChange, and BrowserCustomizeToolbar global window functions have been removed. The customize events fired from the toolbox are now the preferred mechanism for hooking new logic into the customization feature.

Add-on SDK Australis APIs

If you're using the Add-on SDK, there are several new APIs for building your add-on's user interface in Australis. See the reference documentation. Also note that the widget module has been deprecated in favor of the new APIs.

Changes for themes

We've changed the tab markup. If you style these differently, you'll need to check whether it still works.

We'll be drawing tabs in the titlebar and on top, on all platforms (currently implemented on Windows and OS X), except when not showing tabs at all (in popup windows).

Support for small icons mode as well as text and icons mode have been removed.

We've changed the default iconsets, and there are new icon sizes for the menupanel. If you're building on the default theme with new icons, you'll need to rearrange your icons in your Toolbar icon files. In both this case and if you supply a complete theme, you will also need to provide icons for the menu panel. The new icon sizes are the same on all platforms and are:

  • Toolbars:
    16px (32px @2dppx) without padding.
    Internal icons on the navbar use 18px. For add-ons, by default the padding is set up so it should work well if add-ons specify an icon of size 16px.
  • Menu panel/Customization area (palette):
    32px (64px @2dppx)
    Please note that smaller icons will be upscaled.

We've removed the add-on bar, but have a shim in place to migrate icons to other places. Any styles pertaining to should be removed so as not to disturb the migration work.

We've changed a few toolbarbutton IDs, such as those for the bookmark and history buttons. We also added new ones.

The application (Firefox) menu has been removed.

The back, forward, stop and refresh buttons will no longer be movable. They will always remain in their current position next to the urlbar. Your CSS rules can probably be simplified now that this is the case.

The navigation toolbar can no longer be hidden e.g. for update pages or in-content UI.
 

  • Add-ons that have copied their toolbarbutton-insertion code from Adblock Plus hide their toolbarbutton icon. They keep track of their insertion point by themselves. Even though our compatibility shims correctly insert these button initially, their detection code decides it is not in a toolbar (it is in fact in a customization target inside a toolbar, see above) and removes the icon on restart. This has been fixed in Adblock Plus but add-ons using similar code patterns might still be affected.
  • Many add-ons check whether their button is in the toolbox (rather than in a toolbar or some other visible place) by checking the result of document.getElementById(). This is no longer enough. If your button is in the menu panel, it will not be moved there until the menu panel is first shown. Instead, use: CustomizableUI.getPlacementOfWidget("mytoolbarbuttonId"). This will return null if and only if the widget is in the palette.
  • If a <menulist> element is wrapped inside a toolbaritem, popping up the <menulist> closes the new menu panel. This issue is being tracked here.
  • Add-ons that automatically re-add their icons to the add-on bar when removed will need to fix their own insertion code to not do that.
  • Elements inserted in the statusbar element or the add-on bar itself will not be shown. This can only be fixed by the add-on authors, who need to update their add-on to use toolbaritems instead of statuspanels, and insert into a normal toolbar.
  • For toolbaritems and toolbarbuttons inserted into the add-on bar, we will attempt to migrate them to a visible toolbar automatically if the add-on bar was visible in the user's profile before migrating to Australis. However, depending on your add-on's code this may or may not work correctly without further code changes on your part.
  • Toolbar buttons of type menu with a orient="horizontal" attribute will not display properly in the menu panel. This attribute should probably be avoided altogether.

See Also

Document Tags and Contributors

Tags: 
 Last updated by: bunnybooboo,