Packaging Firefox/Thunderbird Themes

Ben Goodger, 05/17/2004

Introduction

This document describes how to package themes for Firefox 0.9 and newer, and Thunderbird 0.8 and newer.

Pre-requisites

This document assumes you've already created a theme, or know a little bit about it at least. Making a theme for Firefox or Thunderbird requires knowledge of Cascading Stylesheets (CSS), probably XBL, and some graphic design and aesthetic skill (...or maybe not ;-) This document describes only how Themes are packaged in order to be shown in Firefox's Themes window.

Theme File Layout

New Firefox/Thunderbird themes are laid out like so:

theme.jar:
              install.rdf
              contents.rdf
              preview.png
              icon.png
              browser/*
              global/*
              mozapps/*
              communicator/*
              ...

You must have a toplevel contents.rdf file that registers the chrome for the theme (as before) and also an install.rdf manifest that specifies metadata that is displayed in the Themes window. preview.png is a preview image which will show in the scrolling preview area in the Themes window. It can be any size. icon.png is a 32x32 png (may contain alpha transparency) which will show up in the Themes list in the Themes window.

install.rdf

Your install.rdf manifest will look something like this:

<?xml version="1.0"?>

<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:em="http://www.mozilla.org/2004/em-rdf#">

  <Description about="urn:mozilla:install-manifest">
    <-- properties -->
  </Description>      
</RDF>

Compulsory install.rdf Properties

Your install.rdf file must have these properties:

em:id

The string GUID of the theme - you can create these by using guidgen (Windows), uuidgen (Unix) or "botbot uuid" on IRC. e.g.

<em:id>{daf44bf7-a45e-4450-979c-91cf07434c3d}</em:id>

em:version

A Firefox Version Format (FVF) string identifying the version of the theme. e.g.

<em:version>4.6</em:version>

em:targetApplication

A object specifying an application targeted by this theme. This means that the theme will work with the application identified by the GUID (em:id), from the min version (em:minVersion) up to and including the max version (em:maxVersion). A theme manifest must specify at least one of these properties, and may specify more if the theme targets multiple apps that support this theme system (e.g. Firefox and Thunderbird). e.g.

  <em:targetApplication>
    <Description>
      <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
      <em:minVersion>0.7</em:minVersion>
      <em:maxVersion>1.2</em:maxVersion>
    </Description>
  </em:targetApplication>

em:name

The name of the theme - intended for display in the UI. e.g.

<em:name>Plastic Fantastic</em:name>

Optional install.rdf Properties

Your install.rdf file may have these properties in addition to the ones above:

em:description

A short description of the extension - intended for display in the UI. Should fit on one short line of text. e.g.

<em:description>Advanced foo tools.</em:description>

em:creator

The name of the creator/principal developer - intended for display in the UI. e.g.

<em:creator>John Doe</em:creator>

em:contributor

The name(s) of contributors to the extension - intended for display in the UI. Your manifest can specify 0 or more of these properties. e.g.

<em:contributor>Jane Doe</em:contributor>

em:homepageURL

A link to the extension's home page - intended for display in the UI. e.g.

<em:homepageURL>http://www.foo.com/</em:homepageURL>

em:updateURL

A link to a custom RDF file that specifies available updates to the extension. The format is described below. If enabled, the extension system periodically checks with this RDF file to determine if newer versions are available. It is recommended you do not supply this field if you are listing your extension with a host such as update.mozilla.org and just use the default update service provided by that host. Your server must send this file as text/rdf or the update checker will not work. Firefox will substitute the following values into this URL in case you wish to generate the response RDF dynamically, such as using PHP or CGI:

`%ITEM_ID%`	The GUID of the extension being updated
`%ITEM_VERSION%`	The version of the extension being updated
`%APP_ID%`	The GUID of the current application
`%APP_VERSION%`	The version of the current application

e.g.

<em:updateURL>http://www.foo.com/update.cgi?id=%ITEM_ID%&version=%ITEM_VERSION%</em:updateURL>

em:internalName

This must be the same as the chrome:name property used in your contents.rdf file, e.g. for the default theme, this string is "classic/1.0". It must match perfectly, including case, otherwise your theme will not apply.

Sample install.rdf File

<?xml version="1.0"?>

<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:em="http://www.mozilla.org/2004/em-rdf#">

  <Description about="urn:mozilla:install-manifest">
    <em:id>{18b64b56-d42f-428d-a88c-baa413bc413f}</em:id>
    <em:version>1.0</em:version>
    
    <!-- Target Application this extension can install into, 
         with minimum and maximum supported versions. --> 
    <em:targetApplication>
      <Description>
        <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
        <em:minVersion>0.8</em:minVersion>
        <em:maxVersion>0.9</em:maxVersion>
      </Description>
    </em:targetApplication>
    
    <!-- Front End MetaData -->
    <em:name>New Theme 1</em:name>
    <em:description>A test theme for Firefox</em:description>
    <em:creator>Ben Goodger</em:creator>
    <em:contributor>John Doe</em:contributor>
    <em:homepageURL>http://www.bengoodger.com/</em:homepageURL>

    <!-- Front End Integration Hooks (used by Theme Manager)-->
    <em:internalName>newtheme1</em:internalName>
  </Description>      

</RDF>

Firefox Version Format

All themes must use the Firefox Version Format to describe their versioning. The FVF looks like this:

major.minor.sub[+]

e.g. 1.2.1 and 0.8+. "+" indicates that the item is from the "development" period between releases.

Not all fields are necessary, e.g. 1.2 is as valid as 1.2.0

Application IDs

The following are some common target application GUIDs that you can use in your targetApplication properties:

Firefox {ec8030f7-c20a-464f-9b0e-13a3a9e97384}

Thunderbird {3550f703-e582-4d05-9a08-453d09bdfdc6}

Custom Update RDF

As described above, a theme can provide its own custom update URL which takes the form of a RDF file. Presently this file must be served as text/rdf. See em:updateURL above for details of the URL format. The RDF file must be formatted like so:

  <RDF:Description about="urn:mozilla:extension:{THEME GUID}">
    <em:version><Version Number Being Offered></em:version>
    <em:updateLink><XPI URL></em:updateLink>
  </RDF:Description>

e.g.

  <RDF:Description about="urn:mozilla:extension:{THEME GUID}">
    <em:version>5.0</em:version>
    <em:updateLink>http://www.foo.com/theme-5.0.jar</em:updateLink>
  </RDF:Description>

Firefox	`{ec8030f7-c20a-464f-9b0e-13a3a9e97384}`
Thunderbird	`{3550f703-e582-4d05-9a08-453d09bdfdc6}`