XUL Tutorial - Manifest Files

In this section, we'll see how to put chrome and XUL files into a package and create manifest 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 refered to with chrome URLs.

A package can contain any files it wants 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.

There are two ways to store packages, either as a directory or as a JAR archive. Each package will have a manifest 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 is a file in RDF (Resource Description Framework) format. We'll learn more about RDF later.

Manifest Files

The contents.rdf file describes the contents of a package. It can also be used to describe a skin and locale.

Manifest 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:component"/>
  </RDF:Seq>

  <RDF:Description about="urn:mozilla:package:component"
        chrome:displayName="title"
        chrome:author="name"
        chrome:name="component">
  </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. Since RDF is an XML format, it contains the standard first line that XML files do. Next, we declare the namespaces that are being used, here 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 top of the manifest file.

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

These lines are used to declare what packages, skins and locales the manifest describes. In this case, a package is being described (as indicated by the word package in the text). The name of the package here is 'component'. 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 RDF:li tag above is much like the li tag of HTML in that 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'. Similarly 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>

Note that the only difference in syntax is the change of the two occurances of the word 'package' to 'skin' and the skin name 'blueswayedshoes'.

  <RDF:Description about="urn:mozilla:package:component"
        chrome:displayName="title"
        chrome:author="name"
        chrome:name="component">
  </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:

• displayName
  The title of the package as it would be displayed to the user. For example 'Messenger'.
• author
  The name of the author of the package.
• name
  The name of package, skin or locale. Usually, this would be the name of the directory it is in.

<?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>

chrome://findfile/content/findfile.xul

Installing a Package

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

Convieniently, we don't have to edit this file directly. Whenever Mozilla starts up, it checks the chrome directory for a special file called 'installed-chrome.txt'. This file contains a list, in a very simple format, of all the packages, skins and locales that are waiting to be installed. Mozilla scans each entry in the list and installs each one, or updates it as necessary.

So, to install a new package, all you need to do is add an entry to the file 'installed-chrome.txt' and restart Mozilla. Mozilla's XPInstall system will allow scripts to install packages automatically via JavaScript without having to modify this file manually. However, during development, we can modify the file directly.

The file 'installed-chrome.txt' should be added directly into the chrome directory, if it not already there. The file contains a list of entries to install, one per line. For example:

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

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:

• Type
  The first value should be set to 'content' for chrome packages, 'skin' for skins or 'locale' for locales.
• Install
  The second value should be set to the text 'install' to have the entry installed. For skins and locales, you can also set it to 'profile' to have the entry installed in the user profile directory. This would mean that it would only be installed for a particular user.
• URL Type
  Set to the text 'url' to specify a URL where the new package, skin or locale is stored. If you use 'path' instead, you can use a file path (which should be in the format of your operating system).
• URL
  The URL (or path) of the location where the package is located. This should be the directory which contains the contents.rdf file or the JAR file. Since it refers to a directory, make sure there is a slash at the end.

The resource URL is similar to a file URL except that its root is the directory where Mozilla is installed. When specifying a URL make sure to end a directory in a slash. The resource URL should also have only one slash after the colon.

Thus, 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,path,/main/calculator/

If you 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 with-in the archive. The example below might refer to the find files dialog:

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

Summary

In summary, the following steps are needed to install a package, skin or locale. You do not need to install XUL files, but you will be limited in what scripts will be allowed to do.

1. Create a directory for your package, skin or locale. Convention states that you should have a subdirectory which is either 'content', ' skin' or 'locale' and within that, a subdirectory with the same name as the package.
2. Create a contents.rdf file as described above and add it into the directory.
3. Create the file 'installed-chrome.txt' in the chrome directory if it isn't already present and add a line pointing to the directory. You should also delete the various RDF files in the chrome directory. This will cause them to be deleted.
4. Start Mozilla. The new package will be installed automatically.

(Next) In the next section, we will create a simple window.