Some notes about Phoenix

This page describes some things about developing for Phoenix, which is a Mozilla browser with a re-designed UI. For the most part, it is similar, so you should be able to port any utilities to it with ease.

Also see: Converting Extensions to Phoenix.

Both the Mozilla browser and the Phoenix browser use XUL for their UI. Mozilla stores its XUL files in the 'navigator' package whereas Phoenix stores its XUL files in the 'browser' package. When referring to the browser for each application, you need to use a different chrome URL for each:

Mozilla Navigator: chrome://navigator/content/
Phoenix: chrome://browser/content/

Each browser uses the 'toolkit' package to hold general-purpose files such as common dialogs and widget definitions stored in XBL files. Phoenix stores some of the definitions for its basic XUL widgets in a slightly different place than the Mozilla browser. For example, for the button element:

Mozilla Navigator: chrome://global/content/bindings/button.xml
Phoenix: chrome://global/content/widgets/button.xml

In the case of the button, there isn't really any difference between the two files except that they point to different places. Many of the Phoenix files are in the bindings directory instead because they are the same, although that may change with later releases. The most dramatic differences come in the toolbar and autocomplete widgets.

Toolbar Customization

Phoenix includes toolbar customization, which allows the user to rearrange the buttons on the toolbars or add other buttons. In 0.2 builds, users can also add additional toolbars to add buttons to. There are two reasons why you may wish to know more about how toolbar customization works. First, to create your own extension which adds one or more custom toolbar buttons. Second, you may wish to use the toolbar customization feature for your own application.

The binding for the toolbar elements is in the file toolbar.xml. The file toolkit/content/global/customizeToolbar.xul is the UI for the customize window itself which pops up when the Customize command is selected. Its associated script, customizeToolbar.js handles adjusting the toolbars as necessary.

To support the customizing of toolbars, a number of new XUL elements are defined in the toolbar bindings file toolbar.xml, along with some changes to the existing elements. Apart from removing the grippies on the left of the toolbars, none of the changes should make existing code incompatible. Changes are listed in the element reference.

Like with Mozilla, the toolbox element surrounds a group of toolbars. It should also surround the menu. Each toolbox contains one or more toolbar elements. If a toolbar can be customized, you should add the customziable attribute to the toolbar, set to the value true. If set, the current arrangement of toolbar items is saved when the user closes the window. It uses the persist feature, so the information is stored in the file localstore.rdf in the user's profile directory. Two pieces of information are stored, the arrangement of the buttons on the toolbars, and what toolbars are displayed.

Unlike with Mozilla, you don't place buttons or other elements inside the toolbar directly. Instead, you place the complete list of buttons inside a new element, toolbarpalette. This element should hold all of the available buttons that can be displayed on the toolbar, not just those that are displayed by default. All of these buttons can be added using the customize dialog.

Inside the toolbarpalette, you place the individual toolbarbutton and toolbaritem elements that can be added to the toolbar. The former is used for button types, and works the same as in Mozilla, while the latter is used for non-buttons, such as the address field and search field. The toolbaritem is just a wrapper, so any content placed inside it will be a single item on the toolbar. It could be used to hold any type of element, or a group of elements. The buttons and items must have an id attribute, as that is how they are referenced during toolbar customization.

The Phoenix browser contains a toolbarpalette, which contains items for the navigation buttons, address bar and a few others. If you want to build your own extension which adds one or more buttons to those available, all you need to do is create an overlay which overlays the toolbarpalette in Phoenix, which has the id of BrowserToolbarPalette. For example:

<toolbarpalette id="BrowserToolbarPalette">
<toolbarbutton id="decreaseFont" class="toolbarbutton-1"
<toolbarbutton id="increaseFont" class="toolbarbutton-1"

This example adds two buttons, one to decrease the font size and the other to increase the font size. Then, you just need to apply a stylesheet to add icons for the buttons, localize it with a DTD if necessary, and package it into an XPI.

The toolbar element has a number of extra attributes used for toolbar customization. The defaultset attribute lists the default set of items that should appear on the toolbar. It should be set to a comma-seperated list of IDs of buttons or items from the toolbarpalette. For example:

<toolbar id="nav-bar" toolbarname="Navigation" customizable="true"

This toolbar contains four buttons by default, a back button, the forward button, and the two font size changing buttons defined above. The binding for the toolbar will take this list and construct buttons as needed. Another attribute currentset is used to hold the current list of buttons that the user has configured. It is this attribute which is persisted into the local store. It has the same format as the defaultset attribute.

Three special IDs can be used also:

These items are handled by the toolbar customization automatically. You shouldn't create buttons with these IDs. The three items above can be placed on the toolbar multiple times, unlike other buttons and items which can only appear once in each toolbox.

A toolbar should also have a toolbarname attribute. In Phoenix, this name appears in the View menu.

In case your wondering, two additional attributes, iconsize and mode, store the icon size and whether icons or text are displayed. These attributes should be placed on the toolbox and are inherited by the toolbars.

Any built-in toolbars are creating using the toolbar element, as in Mozilla. You should add a single toolbarset within the toolbox also to hold any custom toolbars the user might add.

It is possible to have multiple toolboxes in a window, but you won't be able to drag items between them.

Thus, the general structure of a toolbox is as follows, simplified greatly:

    <toolbarbutton id="back-button"/>
    <toolbaritem id="url-bar">
  <toolbar id="nav-bar"/>
  <toolbarset id="customToolbars"/>

This example has two items that can be added to a toolbar, in addition to the spacing items. It includes one toolbar by default, nav-bar, but others can be added by the user and are placed in the toolbarset.

Somewhere in your application you should also add a menu command or button to open the customize dialog. The following is similar to what Phoenix uses to open a customize dialog:

var toolbox = document.getElementById("navigator-toolbox");
toolbox.customizeDone = BrowserToolboxCustomizeDone;

A customizeDone property is added the the toolbox, set to the name of a function. This function will be called when the toolbar customization is completed. Phoenix uses this to update the Address field and re-enable some menu commands. The customize dialog is opened and passed the toolbox as an argument. The magic of disabling the toolbar buttons from activating, dragging items around, and saving state is handled for you.


Autocomplete text boxes are handled a bit differently in Phoenix than in Mozilla. In Mozilla, you use the searchSessions attribute to specify the data to look up, whereas in Phoenix, you use the autocompletesearch attribute. Many of the properties are also different. Those will be documented later.

Copyright (C) 1999 - 2002