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, its GUID, etc.
Installer Manifest
The installer 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 installer manifest, let us take a look at a sample. All of the data which we will need to edit has been highlighted, while all the data we must not edit is displayed in plain text. After we look at the file’s contents, I will explain each piece in detail (and 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:version>1.0</em:version>
<em:targetApplication>
<Description>
<em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
<em:minVersion>1.5</em:minVersion>
<em:maxVersion>3.6.*</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. The second line, which begins with the opening <RDF> tag, is the root element of the document. Its responsibility is to identify this as an RDF (Resource Description Framework) file. The next tag (<Description>) likewise identifies this is an installer 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:version>1.0</em:version>
The first thing we need to worry about is the extension ID. Prior to Firefox 1.5, an extension’s ID had to be specified using a globally unique identifier (GUID). Although GUID’s are still supported, the new format is much easier to use. Simply use the name of your extension (all one word), an @ symbol, and the URL to the top level domain of your website. 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 Extension 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, because the version number has its own tag. That tag happens to be the next one we need to edit. Since this is our first attempt at a toolbar extension, let’s use the 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. 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 installer manifest. Let’s take a look at it now:
<em:targetApplication>
<Description>
<em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
<em:minVersion>1.5</em:minVersion>
<em:maxVersion>3.6.*</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 1.5 for the minVersion and 3.6.* for the maxVersion. Because we are making use of extension development improvements available only in Firefox 1.5, we cannot set the the minVersion value to less than 1.5; otherwise we would have to throw out all of the improvements that we now have available to us.
Note that the version values you use for these two elements must follow a standard convention. For example, a value of "1.5 Release Candidate 1" will not suffice. The current Firefox versioning scheme is fairly strict, and is detailed in the Toolkit Version Format article at the Mozilla Developer Center. I recommend you read the article, to get a feel for 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.
The rest of our installer 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 Extension 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 Extension 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 Installer Manifests article at the Mozilla Developer Center. 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 installer 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:version>1.0</em:version>
<em:targetApplication>
<Description>
<em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
<em:minVersion>1.5</em:minVersion>
<em:maxVersion>3.6.*</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
The chrome manifest is new to Firefox 1.5. Previously, all of the data contained in this file appeared in two places: some of it in the installer manifest, and other portions in a contents.rdf file. The new format is much simpler. 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/
A chrome manifest is how we tell Firefox what packages and overlays our extension provides. Let us again 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/
Compared to the old contents.rdf file (which was usually on the order of 20 lines long), this is incredibly simple! 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 (although it’s a very simple process). 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 in chapter 5).
That was easy, wasn’t it? Below is the final chrome manifest we will use for our tutorial (well, it’s the semi-final version; we’ll come back and add skinning information later). Again, 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!