Contents.rdf Files

In this section, we'll see how to put chrome and XUL files into a package and create the contents.rdf files for them.

Packages

A package is a set of XUL files and scripts that define the functionality of a user interface. Packages may be installed into Mozilla and referenced with chrome URLs. A package can contain any kinds of files and may be split into subdirectories for different parts of the package. For example, the bookmarks and history viewer are part of the communicator package, but are stored in different sub-directories.

A package can be stored either as a directory or as a JAR archive. Each package will have a file, contents.rdf, that describes the package. This file will be placed inside the JAR file alongside the files that it describes. The file must be named contents.rdf and be a file in RDF (Resource Description Framework) format. We'll learn more about RDF later.

Contents.rdf Files

The contents.rdf file describes the contents of a package. It can also be used to describe a skin or locale. These files are fairly easy to create once you know how. The template below can be used as a starting point.

<?xml version="1.0"?>
<RDF:RDF xmlns:RDF="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:chrome="http://www.mozilla.org/rdf/chrome#">
  <RDF:Seq about="urn:mozilla:package:root">
    <RDF:li resource="urn:mozilla:package:myapplication"/>
  </RDF:Seq>
  <RDF:Description about="urn:mozilla:package:myapplication"
        chrome:displayName="My Application"
        chrome:author="name"
        chrome:name="myapplication">
  </RDF:Description>
</RDF:RDF>

You can use this template and make some minor changes specific to your package. Let's break this down to understand what each piece does.

<?xml version="1.0"?>
<RDF:RDF xmlns:RDF="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:chrome="http://www.mozilla.org/rdf/chrome#">

These three lines should be placed at the top of the contents.rdf file. Because RDF is an XML format, it contains the standard first line that XML files usually have. Next, we declare the namespaces that are being used, one for RDF and the other for the chrome system. If you don't understand what this means, don't worry. Just add them at the beginning of the file.

<RDF:Seq about="urn:mozilla:package:root">
  <RDF:li resource="urn:mozilla:package:myapplication"/>
</RDF:Seq>

These lines are used to declare what packages, skins and locales are described by the file. In this case, a content package is being described (as indicated by the word 'package' in the text). If you were creating a skin, you would use 'skin' instead of 'package', and if you were creating a locale, you would use 'locale'. The name of the package is 'myapplication'. Of course, you would replace this with the name of the package you were creating. For example, the Mozilla mail application has a name of 'messenger'. The name should be short and meaningful. This name will be used in chrome URLs for the package.

The RDF:li tag above is much like the li tag of HTML as it declares an element of a list. Thus, you can declare multiple packages by using multiple RDF:li tags.

For skins, replace the two occurances of 'package' with 'skin'; for locales, replace the two occurances of 'package' with 'locale'. For example, the following specifies a skin:

<RDF:Seq about="urn:mozilla:skin:root">
  <RDF:li resource="urn:mozilla:skin:blueswayedshoes"/>
</RDF:Seq>

Next, the descriptive part that specifies the name and author of the application:

  <RDF:Description about="urn:mozilla:package:myapplication"
        chrome:displayName="My Application"
        chrome:author="name"
        chrome:name="myapplication">
  </RDF:Description>

This block is used to provide more details of the package, skin or locale. You will need a description for each li that you have. The value of the about attribute should be equal to the resource attribute on the li tag.

The three extra attributes describe extra information about the package:

You can also use a variety of other values as well. When Mozilla registers your package, these values will be added into the chrome registry.

Let's create a contents.rdf file for the find files dialog we'll be creating. It will need to describe the package. Because there are no sub-packages, skins or locales included, it is fairly similar to the template above.

<?xml version="1.0"?>
<RDF:RDF xmlns:RDF="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:chrome="http://www.mozilla.org/rdf/chrome#">
  <RDF:Seq about="urn:mozilla:package:root">
    <RDF:li resource="urn:mozilla:package:findfile"/>
  </RDF:Seq>
  <RDF:Description about="urn:mozilla:package:findfile"
        chrome:displayName="Find Files"
        chrome:author="Whoever"
        chrome:name="findfile">
  </RDF:Description>
</RDF:RDF>

Here, the component is named 'findfile' which means that we'll be able to refer to it using the following chrome URL:

chrome://findfile/content/findfile.xul

Installing a Package

The list of installed packages is stored in the chrome directory in the file chrome.rdf. You shouldn't edit this file directly. It will be automatically changed when you install a new package. Like the contents.rdf files, it is an RDF format file. On first inspection, it looks quite different than the contents.rdf files, but if you are familiar with RDF, you should notice that it is actually very similar.

Whenever Mozilla starts up, it checks the chrome directory for a file called 'installed-chrome.txt'. This file contains a list, in a very simple format, of all the content packages, skins and locales that are installed. If this file is changed, Mozilla scans each entry in the list and registers or updates each one as necessary so that they can be used.

To register a new package, all you need to do is add an entry to the file 'installed-chrome.txt' and restart Mozilla. The new package will be registered and the chrome.rdf file will be regenerated as necessary to contain the newly installed package. Mozilla also has an installation system called XPInstall which will allow scripts to install packages automatically via JavaScript without having to modify this file manually. XPInstall will be described near the end of the tutorial. However, during development, we can modify the installed-chrome.txt file directly.

The file 'installed-chrome.txt' is in the chrome directory. The file contains a list of entries to install, one per line. For example:

content,install,url,resource:/chrome/findfile/content/
skin,install,url,resource:/chrome/findfile/skin/

The above will be used to install the findfiles package and also a skin for it. The format of each line is fairly simple. It's just four values separated by commas:

Notice that the URLs used are 'resource:/' URLs. You could use a file URL as well. The resource URL is similar to a file URL except that it begins with 'resource:' instead of 'file:' and its top-level directory is the directory where Mozilla is installed instead of the root of the file system. This means that it can be used to refer to files in the Mozilla directory or its subdirectories, regardless of where Mozilla has been installed. The resource URL should only have one slash after the colon since its always a relative path.

The line added should point to the directory where the contents.rdf file is located. If you have multiple packages, add a line for each one.

Although Mozilla follows a directory naming convention, you can put the files anywhere you want. For example, the following will install a new package that is located in the directory /main/calculator/.

content,install,url,file:///main/calculator/

You might notice that the existing lines in installed-chrome.txt have yet another URL type, the 'jar:' URL type. If you are packing your files into a JAR file, you can use a JAR URL to refer to it. It has two parts, separated by an exclamation mark (!). The part before is the URL of the JAR file and the part after is the directory or file within the archive. The example below might refer to the find files dialog:

jar:resource:/chrome/findfile.jar!/content/findfile/

However, you don't usually need to worry about JAR URLs when creating your own packages. Instead, you would keep the package expanded and refer to it using file or resource URL types.

Quick Steps

The information above may have been a little confusing. Here is a quick guide to creating a simple package. You may wish to simply follow the steps below and try to work out the details of how package installation works once you are more familiar with XUL.

  1. Create a directory somewhere on your disk. Many people put this as a subdirectory inside Mozilla's chrome directory, but this isn't necessary. The directory could be anywhere and on any disk. Put your XUL files in this directory.
  2. Create a file called contents.rdf and place it in this directory. Copy the text in the box below into the new contents.rdf file. This file is used to identify the application id, its name, author, version and so on.
  3. <?xml version="1.0"?>
    <RDF:RDF xmlns:RDF="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
             xmlns:chrome="http://www.mozilla.org/rdf/chrome#">
      <RDF:Seq about="urn:mozilla:package:root">
        <RDF:li resource="urn:mozilla:package:myapplication"/>
      </RDF:Seq>
      <RDF:Description about="urn:mozilla:package:myapplication"
              chrome:displayName="Application Title"
              chrome:author="Author Name"
              chrome:name="myapplication"
              chrome:extension="true"/>
    </RDF:RDF>
    
  4. Change the highlighted parts of the file above to your own information. The red text 'myapplication' should be the ID of your application. You make this up, but typically, the ID is similar to your application's name. Replace the blue highlighted text above with your application's title and author.
  5. If the 'chrome:extension' field is true, the application is a Mozilla Firefox Extension and it will show up in the Extensions window of the browser. If false, it will not appear.
  6. Save the contents.rdf and make sure it is in the directory you created in step 1.
  7. Open the file <mozilla-directory>/chrome/installed-chrome.txt, where <mozilla-directory> is the directory where Mozilla is installed. Exit Mozilla before you do this.
  8. Next, you are going to register the new application with Mozilla so it will know where to find it. Add a line at the end of installed-chrome.txt pointing to the new directory you created in step 1.
    content,install,url,file:///main/app/
    
    Change the highlighted text to the file URL of the directory. Make sure that it URL ends with a slash and that you press enter at the end of the line. If you aren't sure what the URL is, open the directory created in step 1 into a Mozilla browser and copy the URL from the location field. Note that the reference should always be a directory, not a file.
  9. Delete the file <mozilla-directory>/chrome/chrome.rdf.
  10. Start Mozilla. You should be able to view any XUL files you put into the directory using a URL of the form: chrome://applicationid/content/file.xul where file.xul is the filename. Your main XUL file should be applicationid.xul which you can load using the shortcut URL chrome://applicationid/content/.

If you are creating skin and/or locale portions, repeat the steps above, except that the format of the contents.rdf file is slightly different. Look at the contents.rdf files in other applications for details.

Troubleshooting

Creating a chrome package can often be tricky and it is difficult to diagnose problems. Here are a few tips in case you get stuck.


(Next) In the next section, we will start looking into the XUL language.

Add a note User Contributed Notes
June 24, 2005, 8:49 pm wbecker-some at thing-gmail-some dot thing-com
I did the example as above, and named my folder `TestApp`. I tried to fix it for hours, until it occured to me it might have a problem with case.

Changed it to `testapp` and it worked fine. Well better anyway.

Cheers

Will
June 16, 2005, 8:36 am gabriel dot birke at gmail dot com
While debugging your package in a browser window it's very helpful to set nglayout.debug.disable_xul_cache to true in about:config. This way you can reload the chrome url with the reload button of the browser.
April 3, 2005, 10:18 pm anonymous at hotmail dot com
In windows, when specifying your install location in install-chrome.txt, make sure you encode folder names that contain spaces:
file:///C|/Documents%20and%20Settings/Username/Desktop/findfiles/content/
March 18, 2005, 12:32 pm evilmeow at gmail dot com
I spent something like 30 minutes banging my head against the wall trying to figure out how is it possible that after I close and start Firefox the chrome.rdf file doesn't get regenerated. I even deleted it manually.

Turned out that there was a dead instance of Firefox stuck. After I killed it and started Firefox, the file was regenerated properly.
February 20, 2005, 6:16 am ocsi at debian dot org
I think does not even need to contain one, because it ends in '/>' not simply '>', therefore indicating a closure of that element.
August 9, 2004, 12:45 pm g at g dot com
Note that if your dist/chrome directory is only writable by root, starting Mozilla as another user will not regenerate your chrome.rdf file...
August 8, 2004, 9:06 am slepax at yahoo dot com
Pay attention: the 'contents.rdf' in the Quick Steps section doesn't use the closing </RDF:Description> element.

Which, of course, is acceptable. - Neil

Copyright © 1999 - 2005 XULPlanet.com