The Chrome URL
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 mulitple 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:
The text <package name> is the package name, such as messenger or editor. The <part> is either 'content', 'skin' or 'locale' depending on which part you want. 'file.xul' is simply the filename.
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 that matches the package name and part. Once found, it will look in that JAR file for file.xul. Mozilla will always start looking in the same directory in the JAR file where the associated contents.rdf file is located, which was described in the previous section. This means that if several packages or parts are all located in the same JAR file, files will be located in the right place. For example, the contents.rdf file for the messenger chrome URL above is located in the file messenger.jar and within this archive, the directory 'content/messenger'. This means that 'messenger.xul' will be loaded from that location, and, if you open messenger.jar, you will find that file in that directory. If you are using the expanded form instead of JAR files, the same applies except that Mozilla can go directly to the directory without looking in a JAR file.
If you were to move the file messenger.jar somewhere else and update the location in Mozilla's list of registered chrome packages, Mail 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.
Mozilla is able to figure out which skin and language are currently used and map the appropriate directories into chrome URLs. The file chrome.rdf in the chrome and profile directory and the contents.rdf files are there to tell Mozilla how to do this. That way the user can use any skin or language but the URLs that reference chrome files do not have to be changed. For example, the default navigator.css can be referenced with:
If you change the browser skin, the chrome URL does not change, even through the real location of the files used by the skin change.
The chrome system takes the navigator sections of the content, the current skin and the current locale and groups them together to form a user interface. Here are some more examples, this time for messenger. Note how none of the URLs specify which theme or locale is used and none specify a specific directory.
For subpackages, the same structure can be used. The following URLs will refer to the bookmarks window, listed both for the Mozilla suite and Firefox, since the package name is different in both:
chrome://communicator/content/bookmarks/bookmarksManager.xul (Mozilla) chrome://browser/content/bookmarks/bookmarksManager.xul (Firefox)
You can enter chrome URLs anywhere normal URLs can be used. You can even enter them directly into the URL bar in a Mozilla browser window. If you enter one of the URLs 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:
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 navigator.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 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. The only rule is that the filename part of the chrome URL refers to files located in the same directory where the associated 'contents.rdf' is located.
(Next) In the next section, we will look at how to create contents.rdf files and packages.