The following section will describe how to refer to XUL documents and other chrome files.
The Chrome URL
XUL files can be referenced with a regular HTTP URL (or any type of URL) just like HTML files. However, packages that are installed into Mozilla's chrome system can be referenced with special chrome URLs. The packages included with Mozilla will already be installed but you can register your own.
Installed packages have the advantage that they don't have security restrictions placed on them, which is necessary for many applications. Another advantage over other URL types is that they automatically handle multiple themes and locales. For example, a chrome URL lets you refer to a file in the theme such as an image without needing to know which theme the user is using. As long as the filenames are the same in each theme, you can refer to the file using a chrome URL. Mozilla will take care of determining where the file is located and return the right data. This also means that it doesn't matter where the package is installed to be able to access it. The chrome URLs are independent of where the files might physically be located. This makes it much easier to write applications that have lots of files since you don't have to worry about the details of locating files.
The basic syntax of a chrome URL is as follows:
chrome://<package name>/<part>/<file.xul>
The text <package name> is the package name, such as messenger or editor. All package names are case insensitive, but lowercase names are preferred. The <part> is either 'content', 'skin' or 'locale' depending on which part you want. <file.xul> is simply the filename.
Example: chrome://messenger/content/messenger.xul
The example here refers to the messenger window. You could point to a file that is part of a skin by replacing 'content' with 'skin' and changing the filename. Similarly, you can point to a file that is part of a locale by using 'locale' instead of 'content'.
When you open a chrome URL, Mozilla looks through its list of installed packages and tries to locate the JAR file or directory that matches the package name and part. The mapping between chrome URLs and JAR files are specified in the manifest files stored in the chrome directory. If you were to move the file messenger.jar somewhere else and update the manifest file accordingly, Thunderbird will still work since it doesn't rely on its specific installed location. By using chrome URLs we can leave details like this to Mozilla. Similarly, if the user changes their theme, the 'skin' part of the chrome URL translates to a different set of files, yet the XUL and scripts don't need to change.
Here are some more examples. Note how none of the URLs specify which theme or locale is used and none specify a specific directory.
chrome://messenger/content/messenger.xul chrome://messenger/content/attach.js chrome://messenger/skin/icons/folder-inbox.gif chrome://messenger/locale/messenger.dtd
To refer to subdirectories, you can just add them to the end of the chrome URL. The following URL will refer to the bookmarks window, listed for Firefox:
chrome://browser/content/bookmarks/bookmarksManager.xul
You can enter chrome URLs anywhere normal URLs can be used. You can even enter them directly into the URL bar in a Firefox browser window. If you enter the URL mentioned above into the browser's address bar, you should see that window appear like a web page might do and for the most part will function as if it was a separate window. Some dialog boxes may not work right, however, as they may be expecting arguments to be supplied from the window that opened them.
You will also see chrome URLs without specified filenames, such as:
chrome://browser/content/
In this case, only the package name and part is specified. This type of reference will automatically select an appropriate file from that right directory. For content, a file with the same name of the package and a xul extension is selected. In the above example, the file browser.xul is selected. For messenger, messenger.xul would be selected. When creating your own applications, you will want to create a file for your main window with the same name as the package, so it can be referred to using this shorter form. This is convenient since all a user needs to know is the package name to be able to open the application. Of course, for extensions that modify the browser interface, the user will not need to know the URL, as the extension will present itself in the UI.
For a skin, the file <package name>.css is selected; for a locale, the file <package name>.dtd is selected.
Remember, the chrome URL is not related to where it is located on disk. The first two pieces of the chrome URL are the package name and the part (either content, skin, or locale). While it is common to put the content files in a directory called 'content', this is purely out of convention, and these files may be placed in an entirely different structure.
In the next section, we will look at how to create .manifest files and packages.