NOTE:

This document is 2 years out of date. For more up to date and correct information, please see MDC Extensions!

Writing Firefox/Thunderbird Extensions - PRELIMINARY

Ben Goodger, 05/02/2004

Introduction

This document describes how to create extensions for Firefox 0.9 and newer, and Thunderbird 0.7 and newer.

Pre-requisites

You must know XUL, JavaScript and other languages/technologies that are required to put your extension together. There are plenty of resources that describe this, and much sample code. This document focuses on how to package XUL, JS and other components together into an extension.

Extension File Layout

New Firefox/Thunderbird extensions are laid out like so:

extension.xpi:
              extension.rdf
              chrome/extension.jar
              components/extension.dll
              components/extension.js
              defaults/extension.something
              defaults/preferences/extension.js

install.js scripts are no longer used for Firefox and Thunderbird extensions. If you provide an install.js script, it will not be read. The new Extension Manager uses the extension.rdf manifest at the top of your extension XPI to handle the installation automatically. You can provide an install.js if your extension also targets another application such as Mozilla 1.x. Those applications will ignore the extension.rdf manifests and use the script instead.

The layout of your files within the XPI is now enforced. You must place jar files you want to register chrome for in the chrome subdirectory, XPCOM components in components, defaults files other than default preferences files in defaults and default preferences files in defaults/preferences. The Extension Manager checks these various locations during startup, installation and uninstallation to perform various operations such as chrome registration automatically, loading of default prefs and so on.

extension.rdf

Your extension.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:extension:manifest">
    <-- properties -->
  </Description>      
</RDF>

Compulsory extension.rdf Properties

Your extension.rdf file must have these properties:

em:id

The string GUID of the extension - 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 that is being supplied by this package. e.g.

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

em:targetApplication

A string specifying an application targeted by this extension. The string is in the format (app_guid,min_app_version,max_app_version) This means that the extension will work with the application identified by the GUID, from the min version up to and including the max version. An extension manifest must specify at least one of these properties, and may specify more if the extension targets multiple apps that support this extension system (e.g. Firefox and Thunderbird). e.g.

<em:targetApplication>{ec8030f7-c20a-464f-9b0e-13a3a9e97384},0.7,1.2</em:targetApplication>

em:name

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

<em:name>My Extension</em:name>

em:file

A chrome .jar file that requires chrome registration. The em:file arcs lead to resources with URIs of the format: urn:mozilla:extension:file:<fileName>.jar. Each of these child resources has a set of em:package, em:locale and em:skin properties that specify the path within the jar file where there is a chrome item that needs to be registered. e.g.

<em:file>
  <Description about="urn:mozilla:extension:file:myext.jar">
    <em:package>content/myext/</em:package>
    <em:locale>locale/en-US/myext/</em:locale>
    <em:skin>skin/classic/myext/</em:skin>
  </Description>
</em:file>

Optional extension.rdf Properties

Your extension.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:optionsURL

The chrome:// URL of the extension's options FE. e.g.

<em:optionsURL>chrome://myext/content/options.xul</em:optionsURL>

em:aboutURL

The chrome:// URL of the extension's about FE. e.g.

<em:aboutURL>chrome://myext/content/about.xul</em:aboutURL>

em:iconURL

A chrome:// URL to a 32x32 icon to display in the Extension Manager UI. e.g.

<em:iconURL>chrome://myext/skin/icon.png</em:iconURL>

Sample extension.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:extension:manifest">
    <em:id>{daf44bf7-a45e-4450-979c-91cf07434c3d}</em:id>
    <em:version>4.6</em:version>
    
    <!-- Target Application this extension can install into, 
        with minimum and maximum supported versions. --> 
    <em:targetApplication>{ec8030f7-c20a-464f-9b0e-13a3a9e97384},0.7,1.2</em:targetApplication>
    
    <!-- Front End MetaData -->
    <em:name>NewExt2</em:name>
    <em:description>A test extension</em:description>
    <em:creator>Joe Creator</em:creator>
    <em:homepageURL>http://www.bengoodger.com/</em:homepageURL>
    <em:updateURL>http://www.bengoodger.com/software/mb/umo/update.rdf</em:updateURL>

    <!-- Front End Integration Hooks (used by Extension Manager)-->
    <em:optionsURL>chrome://newext2/content/options.xul</em:optionsURL>
    <em:aboutURL>chrome://newext2/content/options.xul</em:aboutURL>
    <em:iconURL>chrome://newext2/skin/newext2.png</em:iconURL>
    
    <!-- Packages, Skins and Locales that this extension registers -->
    <em:file>
      <Description about="urn:mozilla:extension:file:newext2.jar">
        <em:package>content/newext2/</em:package>
        <em:locale>locale/en-US/newext2/</em:locale>
        <em:skin>skin/classic/newext2/</em:skin>
      </Description>
    </em:file>
  </Description>      
</RDF>

Firefox Version Format

All extensions 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 TBD.

Custom Update RDF

TBD.

Firefox	`{ec8030f7-c20a-464f-9b0e-13a3a9e97384}`
Thunderbird	`TBD.`