3.11. Overlays
An overlay is a separate file in which additional XUL content can be defined and loaded at runtime. Overlays are often used to define things like menus that appear in different components or parts of the application.
If you are creating a large application or a UI with many elements as a part of your design, the files can easily become large. The size in itself does not render it ineffective, but it does make the job of the developer a little difficult when tracking down and changing features. The best way to overcome this size problem is to use overlays. Another reason to use overlays is to extract information from a certain logical portion of the UI and contain it in a file of its own. This extraction and containment promotes modularization and reusability.
3.11.1. How to Use Overlays
The following declaration is the principal method for including reusable content in a XUL window.
<?xul-overlay href="chrome://global/content/globalOverlay.xul"?>
This declaration follows the same syntax as CSS processing instructions. Like other XML processing instructions, it uses a ? at the beginning and end, just inside the braces. The href attribute points to the overlay and uses Mozilla's chrome:// type URL.
To insert content from an overlay, use the same id of an element in the "base file" for a similar element in your overlay content, and the overlay will replace the base file at runtime (or be merged with it, as described later in this chapter in the Section 3.11.2 section).
When the base element is empty, it is replaced with the corresponding overlay element and any child subcontent. The following toolbar snippet shows a reference placed in a base file:
<toolbar id="main-toolbar" />
When an overlay is read with the content below, the previous line is replaced with that content:
<toolbar id="main-menubar" persist="collapsed"> <toolbarbutton id="new-button" label="New" observes="cmd_new"/> <toolbarbutton id="open-button" label="Open" observes="cmd_open"/> <toolbarbutton id="save-button" label="Save" observes="cmd_save"/> </toolbar>
Overlay files are XUL files with a .xul extension. The content within that file has to be contained in an <overlay> element, which is the root of the document. For example, the toolbar is a first level child of the root.
<overlay id="xflyOverlay"> <toolbar id="main-toolbar" /> <!-- more overlay content --> </overlay>
 | //FIXME did we loose content here? |
| Styles from overlays override styles from base XUL files, so be careful not to load master styles in an overlay. |
3.11.1.1. Dynamic loading
The usual method for loading overlays, as outlined previously, is to include the overlay processing instruction in your XUL file. The dynamic loading of content is more subtle, but just as effective. Mozilla has a registry of overlays, in the form of an RDF datasource that lives in the chrome directory. These overlays live in the tree in a directory called overlayinfo under the chrome root.[1] When a new package or component is registered, the overlays that come with it are loaded automatically.
Dynamic overlays are commonly used to extend certain parts of the Mozilla application itself when new packages are installed that need access points, as do new language packages and themes, for instance. Certain menus in the UI, for example, are open for third-party authors to add items. Adding the name of your package to Mozilla's Tasks menu, for example, provides a convenient launching point and is handled with dynamic overlays. Chapter 6 provides more information on this topic, in the section Section 6.2.3.3.
3.11.2. Content Positioning
Content positioning is the order in which widgets appear in the UI. Usually content is laid out in the order elements are defined in the XUL file. However, there are a couple of ways to override this ordering in XUL.
Continuing with the example of the overlaid toolbar in the previous section, it is possible for both the base definition and the overlaid definition to have children. In this instance, the content is merged, with the original content appearing before the overlaid content by default:
<toolbar id="main-toolbar"> <toolbarbutton id="print-button" label="Print" observes="cmd_print"/> </toolbar>
If the toolbarbutton above is in the base XUL, then the ordering of the buttons would be Print, New, Open, and Save. It is possible to change this ordering by using insertbefore, however, as shown in Example 3-21.
The insertbefore attribute is placed on one of the child items to signify that it should go before a sibling in the base file. insertbefore takes an element id as a value and says, in this case, that the New button should go before Print. Conversely, you can move an item after it by using the insertafter attribute. For more precision, you can use position to position an item absolutely in the sequence of siblings. In Example 3-21, the position attribute puts the Save button in the second position, so the final order is New, Save, Print, and Open.