Creating a status bar extension

In This Article

This is the first in a series of articles that will demonstrate how to create increasingly intricate extensions for the Firefox browser. Some of the samples in this series may be similar to samples you've seen elsewhere, but the goal of this series of articles is to help compile information for new extension developers into one place to make it easy to jump in and get started.

Note: The extension created by this tutorial won't work in Firefox that don't have a static status bar (that is, Firefox 4 and up). You can find a more up-to-date tutorial in the XUL School tutorial The Essentials of an Extension.

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.

Download the sample

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.

Image:status bar sample 1.png

Document Tags and Contributors

Tags:

Contributors to this page: teoli, trevorh, Sheppy, F1Com, Ted_Mielczarek, Mook, Mgjbot, Ptak82, Nickolay, Flashcode20, Waldo

Last updated by: trevorh, Apr 21, 2014, 1:13:05 AM