Tutorials > " . "XUL Tutorial"; $pagetitle="1.4 - Manifest Files"; $customsidebar = "xultu-sidebar.php"; include "header.php"; ?>

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

A package can be stored 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 be 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 or 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: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 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:myapplication"/>
</RDF:Seq>

These lines are used to declare what packages, skins and locales are described by the manifest file. In this case, a package is being described (as indicated by the word 'package' in the text). The name of the package here 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 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>

The only differences are the changes of the two occurances of the word 'package' to 'skin' and the change to the skin name 'blueswayedshoes'.

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

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

So, 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 containing 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 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/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:

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.

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

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. Add a line to the file 'installed-chrome.txt' in the chrome directory pointing to the new directory.
  4. Start Mozilla. The new package will be installed automatically.

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