Building a Thunderbird extension 5: XUL

Thunderbird's user interface is written in XUL and JavaScript. XUL is an XML grammar that provides user interface widgets like buttons, menus, toolbars, trees etc. We add widgets by inserting new XUL DOM elements into the application window and modify them using scripts and attaching event handlers. While XUL provides the elements of the user interface, actions are written in JavaScript.

For our first extension, we will add some text to the Thunderbird status bar. The status bar is implemented in a XUL file called messenger.xul. To view this XUL file use the DOM Inspector extension or look inside the omni.jar archive. In messenger.xul we find the status bar, which looks something like this.:

<statusbar id="status-bar">
 ... <statusbarpanel>s ...
</statusbar>

<statusbar id="status-bar"> is a "merge point" for a XUL overlay. XUL Overlays are a way of attaching other UI widgets to a XUL document at run time. A XUL Overlay is a .xul file that specifies XUL fragments to insert at specific merge points within a "master" document. These fragments can specify widgets to be inserted, removed or modified.

In this example you are adding a line to the indented statusbar. Therefore it becomes an item owned by the id called "status-bar". This shows how the Thunderbird architecture allows extensions to modify the user experience without modifying the installation files. This also enables version independence between Thunderbird and Thunderbird extensions.

Example XUL Overlay Document

<?xml version="1.0"?>
<overlay id="sample" 
xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
 <script type="application/javascript" src="chrome://myfirstext/content/overlay.js"/><!-- A reference to your JavaScript file -->
 <statusbar id="status-bar">
  <statusbarpanel id="my-panel" label="Date"/>
 </statusbar>
</overlay>

The <statusbar> widget named status-bar specifies the merge point within the application window that we want to attach to. When parsing our overlay file, the XUL engine will take all child elements of the <statusbar> tag and merge them with the original XUL document's <statusbar> tag. In the example above we have defined a new <statusbarpanel> item (that can be referred to as my-panel) which will create a new instance of this widget type and add it at the end of the statusbar. In Thunderbird it will appear as a label at the right side of Thunderbird's statusbar and display "Date".  We have also added a <script> tag that contains a reference to the JavaScript file overlay.js. In the next section you will learn how to use JavaScript to modify your label so that it shows the current date.

Take the sample code from above and save it into a new file called myhelloworld.xul within the content folder you created earlier.

The overlay.js file will be created in a later section and your add-on will still work if the file is missing. For now you can ignore this line, but remember that this is how you reference a JavaScript file.

Document Tags and Contributors

Contributors to this page: jenzed, Sheppy, domage, tessarakt, pbenysek, Lanoxx, wbamberg
Last updated by: wbamberg,