Creating Applications with Mozilla
PrevChapter 10. RDF, RDF Tools, and the Content ModelNext

10.6. Manifests

The package descriptions, generally called manifests, use RDF to describe new packages and files to Mozilla. They can be added seamlessly because RDF provides a platform-like environment that facilitates the installation and use of new Mozilla software.

All packages, including the ones that come preinstalled with Mozilla (such as the browser, the MailNews component, and the en-US language pack), have manifests describing them in terms of their relation to other packages. The manifests are typically files called contents.rdf, but they may also be called manifest.rdf. Example 10-15 presents a contents.rdf file that describes a new skin for Mozilla.

Example 10-15. Skin manifest 

<?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#">
<!-- List all the skins being supplied by this theme -->
<RDF:Seq about="urn:mozilla:skin:root">
  <RDF:li resource="urn:mozilla:skin:modern/1.0" />
</RDF:Seq>
<!-- Modern Information -->
<RDF:Description about="urn:mozilla:skin:modern/1.0"
  chrome:displayName="Modern"
  chrome:author="themes@mozilla.org"
  chrome:name="themes@mozilla.org/modern/1.0">
<chrome:packages>
  <RDF:Seq about="urn:mozilla:skin:modern/1.0:packages">
    <--RDF:li resource="urn:mozilla:skin:modern/1.0:aim"/ -->
    <RDF:li resource="urn:mozilla:skin:modern/1.0:communicator"/>
    <RDF:li resource="urn:mozilla:skin:modern/1.0:editor"/>
    <RDF:li resource="urn:mozilla:skin:modern/1.0:global"/>
    <RDF:li resource="urn:mozilla:skin:modern/1.0:messenger"/>
    <RDF:li resource="urn:mozilla:skin:modern/1.0:navigator"/>
  </RDF:Seq>
</chrome:packages>
</RDF:Description>
</RDF:RDF>

As you can see, the manifest is divided up into sections. After the preamble, where the XML processing instruction and the namespace declarations are made, an RDF sequence lists all the themes defined or supplemented (since you can create a package updated for only one Mozilla component, such as the browser) by this package. This section contains only one RDF:li -- the modern theme.

The next section gives more information on the theme, such as the author, the theme name, and a description. The chrome:packages structure that completes the manifest describes the packages to which this theme should be applied. All major components of the Netscape browser are listed in this example -- including the AIM client that is not a part of Mozilla -- but is skinned by themes such as Modern.

10.6.1. RDF and Dynamic Overlays

Manifests can also add new menu items to existing Mozilla menus. When you add a new package to Mozilla, you should make it accessible from within the browser application, where users can access it easily. This is where RDF and dynamic overlays come in.

The RDF you provide in your package makes it possible for the chrome registry, discussed in Chapter 6, to find, understand, and register your new files. Packages must be registered if they are to be skinned, localized, or accessed using the special tools Mozilla provides (e.g., the chrome URL or XPConnect to the XPCOM libraries). If you do not register your package by providing the necessary RDF manifests, it cannot be accessed except as a disparate collection of files in the browser's main content window, which is not what you want.

You can add overlays in Mozilla in two ways: import them explicitly by using an overlay processing instruction at the top of the XUL file into which items in the overlay file are to be "composed," or use RDF to register and load overlay files at runtime. This latter method will be used here to add an "xFly" item to the Tools menu of the Mozilla suite of applications.

Example 10-16 shows the contents.rdf manifest format that alerts Mozilla of the presence of an overlay, its target in the Mozilla application, and the package of which it is a part.

Example 10-16. Overlay for a sample application menu 

<?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:help"/>
  </RDF:Seq>
  <RDF:Description about="urn:mozilla:package:help"
        chrome:displayName="xFly Application"
        chrome:author="xfly.mozdev.org"
        chrome:name="xfly">
  </RDF:Description> 
  <!-- Declare overlay points used in this package -->
  <RDF:Seq about="urn:mozilla:overlays">
    <RDF:li resource="chrome://communicator/content/tasksOverlay.xul" />
  </RDF:Seq>
  <RDF:Seq about="chrome://communicator/content/tasksOverlay.xul">
    <RDF:li>chrome://xfly/content/xflyOverlay.xul</RDF:li>
  </RDF:Seq>
</RDF:RDF>

The manifest in Example 10-16 names the file xflyOverlay.xul as an overlay. Then it names tasksOverlay.xul as the base file into which the contents are placed. In this case, the overlays can overlay other overlay files arbitrarily. An overlay can define new content anywhere in the application. Overlays are often responsible for putting new items in menus. As long as the target and overlay ids match, any two RDF datasources are merged. You can try this example by putting a single new menu item in an overlay structure like the one shown in Example 10-17. Save it as xflyOverlay.xul in the xfly content subdirectory and use the manifest information in Example 10-16 as part of the packaging process described in Chapter 6.

Example 10-17. Overlay for an xFly menu item in the browser 

<?xml version="1.0"?>
<overlay id="xflyMenuID"
        xmlns:html="http://www.w3.org/1999/xhtml"
        xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
  
  <menupopup id="tools_menu">
    <menuitem label="xfly xml editor" 
        oncommand="toOpenWindowByType('mozilla:xfly, 'chrome://xfly/content/');" />
  
</menupopup>
  
</overlay>

The menupopup in Mozilla with the ID "tools_menu" gets a new menu item when this overlay is processed and its content included.

PrevHomeNext
JSLib RDF FilesUpLocalization