{"id":6843,"date":"2013-12-12T12:20:42","date_gmt":"2013-12-12T20:20:42","guid":{"rendered":"http:\/\/blog.mozilla.org\/addons\/?p=6843"},"modified":"2014-03-06T14:31:22","modified_gmt":"2014-03-06T22:31:22","slug":"australis-for-add-on-developers-1","status":"publish","type":"post","link":"https:\/\/blog.mozilla.org\/addons\/2013\/12\/12\/australis-for-add-on-developers-1\/","title":{"rendered":"Australis for Add-on Developers – Part 1: Toolbars"},"content":{"rendered":"

Australis, the new Firefox theme, landed in Nightly 6 weeks ago. Because of the ongoing work being done to it, it won’t be uplifted to Aurora just yet, so it will continue to be available exclusively in the Nightly channel<\/a> for at least one more cycle. That means that Australis won’t be in Firefox before version 29, which is currently scheduled<\/a> to make its final release in late April 2014.<\/p>\n

We encourage you to download the latest Nightly<\/a> and test your add-ons in it.<\/strong> If you’re an add-on developer and run into problems, please let us know, or file a bug<\/a> and add it as a dependency to this tracking bug for add-on issues<\/a> on Australis. Make sure to give the other dependent bugs a look first to prevent duplicates. If you’re not a developer and want to report a problem in one of the add-ons you have installed, you can install the Add-on Compatibility Reporter<\/a> extension and use it to let us know.<\/p>\n

Now let’s start looking into what has changed in Australis that you should know about. If you haven’t installed Nightly yet, you can use the information in this blog post<\/a> as reference.<\/p>\n

Toolbars<\/h3>\n

The toolbars have changed significantly. The objective is to maximize the content area available to users by cutting down chrome areas that were generally empty. There were also deeper changes that enable more complex widgets to be added to the toolbar and other areas without compromising on space.<\/p>\n

The Add-on Bar at the bottom has been removed. Instead, there’s a new menu panel that extends the toolbar with buttons and widgets. It is activated by clicking on the button at the right end of the main toolbar. All the items in this new menu are customizable and it\u2019s possible to add add-on buttons and widgets to it as well.<\/p>\n

The customization UI got a much-needed refresh and now it’s much easier to use and find. The full window view allows users to better understand what they\u2019re doing and have better control over toolbar customization. The possible targets for toolbar buttons are the main toolbar, custom toolbars, the tab bar and the new menu panel. Make sure that your add-on buttons \/ widgets work well for all cases. There’s currently no way to create new blank toolbars, but the Bookmarks Toolbar can be used by users to add buttons. There is no more big icon \/ small icon option.<\/p>\n

The DOM in the main toolbar is also different. Now there’s a intermediate container between the toolbar<\/code> element and its children. It’s an hbox<\/code> with id nav-bar-customization-target<\/code>.<\/p>\n

Toolbar Buttons<\/h3>\n

The icons in the main toolbar are 18×18 pixels. However, a 1px padding is expected, so the 16×16 pixel icons you should be using for the main toolbar in modern versions of Firefox will work without any changes.<\/p>\n

Buttons can be also moved by users or added by default to the new menu panel, so you need to consider this case as well. Icons are 32×32 pixels\u00a0in the menu panel and also during customization, if they are removed from the toolbar. Smaller icons will be upscaled, so they won’t look very good if you use the 16×16 pixel icons.<\/p>\n

So, if you have an add-on that adds a toolbar button to the main toolbar using the usual guidelines<\/a> of overlaying the button to the palette and then adding it to the toolbar using JS on first run, everything should work the same and you should only change your CSS to something like this:<\/p>\n

\/* Original CSS *\/\r\n#my-button {\r\n  list-style-image: url(\"chrome:\/\/my-extension\/skin\/icon16.png\");\r\n}\r\n\/* Added for Australis support *\/\r\n#my-button[cui-areatype=\"menu-panel\"],\r\ntoolbarpaletteitem[place=\"palette\"] > #my-button {\r\n  list-style-image: url(\"chrome:\/\/my-extension\/skin\/icon32.png\");\r\n}<\/pre>\n
Note that buttons in the Australis theme have the cui-areatype<\/code> attribute set when placed in in the UI. The possible values are menu-panel<\/code> and toolbar<\/code>. You can use the toolbar<\/code> value to have different style for the button in Australis and non-Australis themes.<\/p>\n
Buttons with type=\"menu\"<\/code> or type=\"menu-button\"<\/code> show inconsistent appearance and behavior. There are a couple of add-on bugs filed for them, but it’s unclear if they will be fixed, since the subview pattern will be favored for Australis. See how the History button works on the toolbar and the panel for an example of this. The process of implementing this isn’t documented yet, but you can look at the source code<\/a> to get an idea.<\/p>\n
Add-on Bar Buttons<\/h3>\n
As mentioned before, the Add-on Bar was retired to maximize the available content area. However, a shim is in place in the main toolbar to facilitate migration (it even contains the old statusbar shim). However, it doesn’t seem to work at present. I filed this bug<\/a> to keep track of the problem. \u00a0While this does appear to be a bug, we encourage you to insert your button in the main toolbar instead.<\/p>\n
By the way, an easy way to detect if your add-on is installed on a Firefox version with Australis is to check for the existence of this node ID: PanelUI-menu-button<\/code>.<\/p>\n
SDK Add-ons<\/h3>\n
As you may know already, the SDK was integrated into Firefox, so SDK add-ons no longer need to bundle the entire set of libraries, making them more or less independent from the SDK version being used. Version 1.15 of the SDK was just released<\/a>, which generates library-less XPIs by default.<\/p>\n
Since the SDK will be built into Firefox, you can expect your add-ons and widgets to work with Australis. You should keep in mind that it’s possible that widgets will be deprecated in the future for something that works better with Australis, but that’s still being talked about, so keep an eye on this blog for updates.<\/p>\n
More Documentation<\/h3>\n