Tutorials > " . "XUL Tutorial"; $pagetitle="1.3 - The Chrome URL"; $customsidebar = "xultu-sidebar.php"; include "header.php"; ?>

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 just like HTML files (Or any type of URL). However, packages that are installed into Mozilla's chrome system can be referenced with special chrome URLs. Files in the chrome directory 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 skins and locales.

The basic syntax of a chrome URL is as follows:

chrome://<component>/content/<file.xul>

where <component> is the component name, such as messenger or editor.

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'.

You could think of the chrome URL as a special type of file URL (that is, file:// URLs) where the root directory is the Mozilla chrome directory. However, there is one additional feature. The skin and locale part of the chrome URL maps to the current setting. If the user changes the default skin, the chrome URL does not change, but what it points to changes.

Mozilla is able to figure out which skin current language are currently used and map the appropriate directories into chrome URLs. The file chrome.rdf in the chrome 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:

chrome://navigator/skin/navigator.css

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:

chrome://messenger/content/messenger.xul
chrome://messenger/content/mime.js
chrome://messenger/skin/icons/images/folder-inbox.jpg
chrome://messenger/locale/messenger.dtd

For subpackages, the same structure can be used. The following URL will refer to the bookmarks window:

chrome://communicator/content/bookmarks/bookmarks.xul

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. Remember that you can also reference XUL files with regular file URLs also. You might do this to test a file without having to install a package.

You might also see chrome URLs without specified filenames, such as:

chrome://navigator/content/

This type of reference will automatically select an appropriate file from that directory. For content, a file with the name of the package and a xul extension is selected. In the above example, the file navigator.xul is selected.

For a skin, the file package.css is selected; for a locale, the file package.dtd is selected (where package is the name of the package). This is a convenient shorthand syntax.


(Next) In the next section, we will look at how to create manifest files and packages.