Tutorials > " . "XUL Tutorial"; $pagetitle="1.2 - Adding XUL Files"; $customsidebar = "xultu-sidebar.php"; include "header.php"; ?>

Adding XUL Files

We'll begin by looking at how the XUL file system is organized in Mozilla.

Opening XUL Files

If you are going to use XUL on a web site, you can just put the XUL file on the web site as you would an HTML file, and then load its URL in a browser. Ensure that your web server is configured to send XUL files with the content type of 'application/vnd.mozilla.xul+xml'. You can also load XUL files from your own machine by opening them in the browser, or double-click the icon in your file manager. XUL files should have a .xul extension.

However, you can also package XUL into an application which can be installed into Mozilla. The next few sections describe how this system works. However, if you just want to get started building a simple application, you may skip ahead to section 2 and save this section for later.

Package Organization

Mozilla is organized in such a way that you can have as many components as you want installed. A typical installation might have the navigator, messenger and editor components. It will also have one component for each installed skin and locale. Each of these components, or packages, is made up of a set of files that describe the user interface for it. For example, the messenger component will have descriptions of the mail messages list window, the composition window and the address book dialogs.

The packages that are provided with Mozilla are located within the chrome directory, which you will find in the directory where you installed Mozilla. The chrome directory is where all the files that describe the user interface used by Mozilla are located.

Each package may have a number of sub-packages. For example, the messenger package contains two sub-packages, the address book package, and the message composition package.

A package can supply its own skin information as part of the package, or it may rely on the default skin.

The word 'chrome' refers to the user interface elements in an application. For example, in a browser, the chrome part of the window would be the toolbars, the menu and the status bar. The content area of a browser would display a different document.

Chrome Directory Details

A user interface is made up of three sets of files, each stored in a separate subdirectory of the chrome directory. These three sets are the content, the skin and the locale. A particular component might provide one or more default skins and locales, but a user can replace them with their own.

Take a look at Mozilla's chrome directory. You should see a bunch of JAR files, one for each installed package. For example, the file messenger.jar describes the user interface for the Messenger component. The file modern.jar describes the Modern skin.

Distinguishing a Package Type

The name of the JAR file might describe what it contains, but you can be sure by viewing its contents. (You can view JAR files with a ZIP utility). Let's use the messenger package as an example. If you extract the files in messenger.jar, you will find that it contains a directory structure like the following:

      -- other mail XUL and JS files goes here --
         -- address book files go here --
         -- message composition files go here --

This is easily recognizable as a content package, as the top-level directory is called 'content'. For skins, this directory will be called 'skin' and for locales, it will be called 'locale'. Actually, this isn't necessary but you should follow this convention to make your package clearer. Some packages may include a content section, a skin and a locale. In this case, you will find a subdirectory for each type.

The content/messenger directory contains a number of files with xul and js extensions. The XUL files are the ones with the xul extension. The files with js extensions are JavaScript files which contain scripts that handle the functionality of a window. Many XUL files have a script file associated with them.

In the listing above, two files have been shown. There are others of course, but for simplicity they aren't shown. The file messenger.xul is the XUL file that describes the main Messenger window which displays the mail messages list. The main window for a content package should have the same name as the package with a xul extension. Some of the other XUL files are included by messenger.xul or describe separate windows. For example, the file subscribe.xul describes the dialog for subscribing to newsgroups.

The file contents.rdf is found in every package, one for each content, skin and locale in the package. This file is used to describe the contents of the package and will be described in detail later.

Two subdirectories, addressbook and messengercompose, describe additional sections of the Messenger component. They are placed in different directories only to separate them.


The modern.jar and classic.jar files describe the skins provided with Mozilla. Their structure is similar to the content packages. For example, modern.jar:

         -- navigator skin files go here --
         -- messenger skin files go here --
         -- editor skin files go here --
         -- communicator skin files go here --
         -- global skin files go here --

Here, five directories exist, one for each package that the skin is applied to. For example, the editor directory describes the skin for the editor component. The global directory contains skin files that are general to all packages. These files will apply to all components. You will usually use this one yourself.

You might notice that there are five contents.rdf files. This way, the skins are applied separately to each component. You could have a different skin for navigator as messenger, but most of the appearance is determined by the global part so you won't see much difference. They are also separate files so that new components can be added and existing components can be removed easily.

A skin is made up of CSS files and a number of images used to define the look of an interface. The images are used for the toolbar buttons. The file messenger.css is used by messenger.xul and contains styles which define the appearance of various parts of the mail interface.

By changing the CSS file, you can adjust the appearance of a window without changing its function. This is how you can create a skin.


The file en-US.jar describes the language information for each component, in this case for US English. Like the skins, each language will contain files that specify text used by the package but for that language.

As usual, a contents.rdf file is provided that lists the packages the locale provides text for. Subdirectories provide the text for each package.

The localized text is stored in two types of files, DTD files, and properties files. The DTD files have a dtd extension and contain entity declarations, one for each text string that is used in a window. For example, the file messenger.dtd contains entity declarations for each menu command. In addition, keyboard shortcuts for each command are also defined, because they may be different for each language. DTD files are used by XUL files so, in general, you will have one per XUL file.

Properties files are similar, but are used by script files. The file messenger.properties contains a few such strings.

This structure allows you to translate Mozilla or a component into a different language by just adding a new locale for that language.

Other Packages

Many of the packages in Mozilla are sub-packages of the communicator package. For example, you'll find the bookmarks window, the history viewer and the preferences dialogs within the communicator package. They are put there because they are general to a number of packages. There is nothing special about them.

There is a special package called toolkit (or global). We saw the global directory earlier for skins. The toolkit.jar contains the corresponding content for it. It contains some global dialogs and definitions. It also defines the default appearance and functionality of the various widgets such as textboxes and buttons. The files located in the global part of a skin archive contains the default look for all of the XUL interface elements. Most skin changes will involve variations of these files.

Adding a Package

The structure described above is where the default packages, skins and locales are stored. However, they do not need to be placed there. If you have another package installed, it can be placed anywhere on the disk. The file chrome.rdf in the chrome directory stores the list of installed packages, skins and locales and where they are located.

A user may have multiple skins and locales installed that modify the same package. Only one skin and locale per package is active at any given time. The file chrome/chrome.rdf in the user profile specifies which skins and locales are active.

(Next) In the next section, we'll look at how to refer to files in the chrome structure.