Chapter 2: Creating the Framework

An extension’s framework is used to tell Firefox about the extension: how its files are structured, who created it, etc. Two primary files, the install manifest and the chrome manifest, are how we specify the details.

Install Manifest

The install manifest is how we provide details on our extension to Firefox. There are some important items that are placed in this file, so we need to make sure we get this right. Create a new file in your top level folder, and give it the name install.rdf. Here is how the directory structure should look once you’ve created the file:

TutToolbar/
 |-- install.rdf
 +-- chrome/
      +-- content/

Before we begin working with our install manifest, let us take a look at a sample one. All of the lines which we will need to edit have been highlighted. After we look at the entire file’s contents, I will explain each piece in detail so we can begin creating our own.

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

        <!-- Required Items -->
        <em:id>yourextension@yoursite.com</em:id>
        <em:name>Your Extension's Name</em:name>
        <em:type>2</em:type>
        <em:version>1.0</em:version>

        <em:targetApplication>
            <Description>
                <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
                <em:minVersion>4.0</em:minVersion>
                <em:maxVersion>99.*</em:maxVersion>
            </Description>
        </em:targetApplication>

        <!-- Optional Items -->
        <em:creator>Your Name</em:creator>
        <em:description>A description of the extension</em:description>
        <em:homepageURL>http://www.yoursite.com/</em:homepageURL>

    </Description>
</RDF>

The first line above indicates that this is nothing more than an XML file. Next is the root element of the document, which begins with the opening <RDF> tag. Its responsibility is to identify this as a Resource Description Framework (RDF) file. The <Description> tag, further identifies this as an install manifest. Now that all of the boilerplate is out of the way, let’s look at the first part of what we need to edit, all of which is required:

<em:id>yourextension@yoursite.com</em:id>
<em:name>Your Extension's Name</em:name>
<em:type>2</em:type>
<em:version>1.0</em:version>

The first bit of data we need to provide is the extension ID. Simply use an email-address format: the name of your extension (all one word), an @ symbol, and the top level domain of your website. Note that the domain doesn’t really need to exist, but it does need to follow the standard email address convention. This value should also not be your actual email address. Note also that GUID-style IDs are allowable, but the email-style format is much easier to deal with. For the toolbar we are building in this tutorial, let’s use the value tuttoolbar@borngeek.com.

Next up is the extension’s name, as it will appear in the Add-ons Manager. For our example, let’s use the name Toolbar Tutorial. Make sure that you do not include the version number as a part of this name, since the version number has its own tag, which we’ll get to in a moment.

The <em:type> tag must be set to a value of 2, which indicates that this is an extension. This is a value that, once set, you’ll never touch again.

Next up is the extension’s version. Since this is our first attempt at a toolbar extension, let’s use a value of 1.0. Keep in mind that, in the real world, you need to update this value each time you release an updated version of your extension. Also note that the value you supply here should conform to the Toolkit Version Format. Scripters should have no problem writing a small program to automate the version updating process. I utilize such a script (written in Perl) for all of my extensions. In chapter 7 of this tutorial, I will show you how I do it.

The next block of code in this file, which is also required, is one of the most important pieces of the install manifest. Let’s take a look at it now:

<em:targetApplication>
    <Description>
	<em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
	<em:minVersion>4.0</em:minVersion>
	<em:maxVersion>99.*</em:maxVersion>
    </Description>
</em:targetApplication>

This block is responsible for saying what application our extension is intended for. In our case, we are developing an extension for Firefox. As such, the value within the <em:id> element specifies the Firefox GUID. You should not change this value! Doing so will prevent your extension from installing correctly.

The only two sections in this block that we need to touch are the <em:minVersion> and <em:maxVersion> elements. These two elements specify what versions of Firefox our extension should be compatible with (the minVersion being the lowest supported version, and the maxVersion being the highest supported version). For our example, we will be using the value 4.0 for the minVersion and 99.* for the maxVersion.

Note that, as with our extension’s version string, the version values you use for these two elements must adhere to the Toolkit Version Format. I recommend that you familiarize yourself with what version strings are and are not allowed. Also, be sure to take a look at the valid application versions document at the Mozilla add-ons website. This document lists all of the "officially approved" version strings. Extensions you submit to the official add-ons website will be rejected if your maxVersion does not conform to their approved list. The maxVersion that I have used for this tutorial does not conform to the approved version list. I used a large number to prevent from having to bump the version for each Firefox release.

The rest of our install manifest is simply meta-data that describes our extension:

<!-- Optional Items -->
<em:creator>Your Name</em:creator>
<em:description>A description of the extension</em:description>
<em:homepageURL>http://www.yoursite.com/</em:homepageURL>

As the comment suggests, all of these elements are optional. I have chosen three elements to use for this tutorial. The first element, <em:creator>, allows the extension author to specify his name, so that others will know who created the extension. Next, the <em:description> element allows us to provide a short description of our extension. This description will appear in the Add-ons Manager, underneath our extension’s name. Finally, the <em:homepageURL> element allows us to specify where people can find our extension on the web.

Note that these aren’t the only meta-data elements available to us; a number of other optional ones also exist. For example, there is an element to let us use our own icon in the Add-ons Manager. Another element allows us to specify the location of a custom options or about dialog. For an entire list of the available elements (they are also known as properties), take a look at the Install Manifests article at the Mozilla Developer Network. And one final note: all of these elements are not order dependent. In other words, you can place them in any order you like in this file; they simply have to be direct descendants of the first <Description> element that we created.

Now that we know about the install manifest, let’s take a look at our finalized version, which we will be using in this tutorial. Feel free to copy the code below and place it in the install.rdf file that we created moments ago.

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

        <!-- Required Items -->
        <em:id>tuttoolbar@borngeek.com</em:id>
        <em:name>Tutorial Toolbar</em:name>
        <em:type>2</em:type>
        <em:version>1.0</em:version>

        <em:targetApplication>
            <Description>
                <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
                <em:minVersion>4.0</em:minVersion>
                <em:maxVersion>99.*</em:maxVersion>
            </Description>
        </em:targetApplication>

        <!-- Optional Items -->
        <em:creator>Jonah Bishop</em:creator>
        <em:description>An example toolbar extension.</em:description>
        <em:homepageURL>http://www.borngeek.com/firefox/</em:homepageURL>

    </Description>
</RDF>

Chrome Manifest

A chrome manifest is how we tell Firefox what packages and overlays our extension provides. Create another file, again in the top level folder, and name it chrome.manifest. Here is how our directory structure should now look:

TutToolbar/
 |-- install.rdf
 |-- chrome.manifest
 +-- chrome/
      +-- content/

Let us take a look at a sample file before we begin creating our own:

content myextension chrome/content/
overlay chrome://browser/content/browser.xul chrome://myextension/content/overlay.xul

locale myextension en-US chrome/locale/en-US/

skin myextension classic/1.0 chrome/skin/

The first line registers a content package using the package name you specify (the above sample uses myextension), as well as the location to the content folder. Note that the package name must use lowercase letters; a mixed case package name is not allowed, nor is all uppercase. This first line allows chrome URIs like chrome://myextension/content/ to point to the appropriate place in our extension’s hierarchy. Note that the content folder’s location is relative to the root folder of our extension. For our tutorial, we will use a package name of tuttoolbar. The rest of the data shown will stay the same.

The second line registers an overlay for chrome://browser/content/browser.xul. This allows you to add to or modify the user interface in the main Firefox window. In the sample above, the XUL file used as the overlay is specified by chrome://myextension/content/overlay.xul. In other words, the file overlay.xul located in our extension’s content folder is how we will be adding our new user interface controls (our toolbar). The overlay value we will be using for this tutorial is chrome://tuttoolbar/content/tuttoolbar.xul.

The next line demonstrates how a locale can be created. We will not be creating a locale in this tutorial, but I have provided this example to show how to refer to them in the chrome manifest.

The final line sets up a skin, the mechanism we will use to make our toolbar look pretty. For now, let’s ignore it; we will come back to this piece in chapter 5.

That was easy, wasn’t it? Below is the first draft of the chrome manifest we will use for our tutorial. Feel free to copy the code below and paste it into the chrome manifest file we created moments ago:

content tuttoolbar chrome/content/
overlay chrome://browser/content/browser.xul chrome://tuttoolbar/content/tuttoolbar.xul

Now that the framework is in place, let’s have some fun creating our toolbar!