Many of the concepts introduced here apply to any XUL-based application; however, to keep from getting completely overwhelmed, we're going to focus specifically on Firefox.
This sample will add a static text string to the status bar at the bottom of Firefox browser windows. If this sounds a lot like the existing Building an Extension article, you're right. However, this sample will be expanded upon in later articles in the series.
Download the sample
You can download a copy of this sample to look over -- or to use as the basis for your own extension.
The install manifest
The install manifest, install.rdf, is a text file containing information that tells the host application important information about the extension.
<?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>status-bar-sample-1@example.com</em:id> <em:version>1.0</em:version> <em:type>2</em:type> <!-- Front End Metadata --> <em:name>Status Bar Sample 1</em:name> <em:description>Sample static status bar panel</em:description> <em:creator>My Name</em:creator> <em:homepageURL>http://developer.mozilla.org/en/docs/Creating_a_status_bar_extension</em:homepageURL> <!-- Describe the Firefox versions we support --> <em:targetApplication> <Description> <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id> <em:minVersion>1.5</em:minVersion> <em:maxVersion>2.0.0.*</em:maxVersion> </Description> </em:targetApplication> </Description> </RDF>
Let's take a look at some key parts of the manifest.
Extension identification information
Certain information is needed so Firefox can uniquely identify your extension. In this sample, these fields are:
| Property name | Description |
| id | A unique identification string. Before Firefox 1.5, this was a GUID. Starting with Firefox 1.5, however, you should use a string in the form extension-name@creator-domain. |
| version | The extension's version number. |
| type | The addon type. For extensions, this is 2. |
Human-readable information
In this sample, we have four pieces of human-readable information; that is, information that is displayed to the user within the Firefox interface. These are:
| Property name | Description |
| em:name | The extension's name. This name is displayed in the Extensions window. |
| em:description | A short, one-line description of the extension. This text is also displayed in the Extensions window. |
| em:creator | The author's name. |
| homepageURL | The URL of a web site the user can visit to get information about the extension, or to look for updates. This is not a required field, but including it is a nice thing to do. |
Target application information
It's also necessary to include information that identifies the application or applications in which your extension is designed to run. Although this sample extension only works in Firefox, it's entirely possible to create extensions that work in multiple XUL-based applications.
It's also necessary to indicate what versions of the target application or applications your extension supports. If it won't work in older versions of Firefox, or hasn't been tested on newer versions, you can restrict the extension so that only supported versions of the target application will attempt to use it.
The target application information is contained within the em:targetApplication Description block.
| Property name | Description |
| id | An ID indicating the target application. "{ec8030f7-c20a-464f-9b0e-13a3a9e97384}" is a GUID that uniquely identifies Firefox as the target. |
| minVersion | The oldest version of the target application on which the extension is supported. |
| maxVersion | The most recent version of the target application on which the extension is known to work. |
For details on the format of an install manifest, read the Install Manifests section.
The chrome manifest
The chrome manifest is a file that tells the target application where to look for the chrome package for your extension. The chrome is the set of user interface elements outside the content area of the application's window, such as toolbars, status bars, menu bars, and the like.
The chrome manifest file, chrome.manifest, for the sample follows.
content status-bar-sample-1 chrome/content/ # Firefox overlay chrome://browser/content/browser.xul chrome://status-bar-sample-1/content/status-bar-sample-1.xul
The first line registers the location on disk of the contents of the extension whose ID is "status-bar-sample-1". This path is relative to the extension's root folder in this case, but can be absolute if you want it to be.
The second line registers an overlay. An overlay lets you add new content to an existing document. In this case, we want to augment the UI of the Firefox browser, so we specify the URI of the Firefox main window's XUL file, "chrome://browser/content/browser.xul", as the interface to overlay onto, and the URI of our own XUL file, "chrome://status-bar-sample-1/content/status-bar-sample-1.xul", as the interface to overlay onto the browser.
See XUL Overlays for details on how overlays work. You can also find more details about format of chrome manifests in the Chrome Manifest section.
The XUL overlay
The XUL overlay file contains the XUL description of the user interface we want to add to Firefox. Our overlay file, status-bar-sample-1.xul, looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE overlay >
<overlay id="status-bar-sample-1-overlay"
xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
<!-- Firefox -->
<statusbar id="status-bar">
<statusbarpanel id="status-bar-sample-1"
label="Hello World"
tooltiptext="Sample status bar item"
/>
</statusbar>
</overlay>
The first order of business in the status-bar-sample-1.xul file is to establish that this is in fact a XUL file, and to set up a unique ID for the overlay. This is accomplished by the following line of XML:
<overlay id="status-bar-sample-1-overlay"
xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
Once that's accomplished, we can describe our user interface. In this case, we're simply inserting a new panel into the status bar at the bottom of Firefox browser windows. We do this by embedding inside the statusbar named "status-bar" -- which is the Firefox browser window's status bar -- a new statusbarpanel object we call "status-bar-sample-1".
We include properties to configure our new status bar panel the way we want, setting its text label to "Hello World" and establishing a tool tip with the message "Sample status bar item" in it.
Trying it out
To test your extension, drop the folder into the extensions folder in your Profile Folder. Then restart Firefox, and you should see the extension in the status bar.
