Creating a status bar extension

  • Revision slug: Creating_a_status_bar_extension
  • Revision title: Creating a status bar extension
  • Revision id: 33239
  • Created:
  • Creator: Ptak82
  • Is current revision? No
  • Comment pl

Revision Content

{{template.Next("Creating a dynamic status bar extension")}} 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.

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, <tt>install.rdf</tt>, 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:name>
   <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, <tt>chrome.manifest</tt>, 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, <tt>status-bar-sample-1.xul</tt>, 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 <tt>status-bar-sample-1.xul</tt> 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.

<center>

Image:status bar sample 1.png

</center>

{{template.Next("Creating a dynamic status bar extension")}}

{{ wiki.languages( { "pl": "pl/Tworzenie_rozszerzenia_paska_stanu" } ) }}

Revision Source

<p>
{{template.Next("Creating a dynamic status bar extension")}}
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.
</p><p>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.
</p><p>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 <a href="en/Building_an_Extension">Building an Extension</a> article, you're right.  However, this sample will be expanded upon in later articles in the series.
</p>
<h2 name="Download_the_sample">Download the sample</h2>
<p>You can download a copy of this sample to look over -- or to use as the basis for your own extension.
</p><p><a class="external" href="http://developer.mozilla.org/samples/extension-samples/status-bar-sample-1.zip">Download the sample</a>
</p>
<h2 name="The_install_manifest">The install manifest</h2>
<p>The install manifest, <tt><a href="en/Install_Manifests">install.rdf</a></tt>, is a text file containing information that tells the host application important information about the extension.
</p>
<pre class="eval"> &lt;?xml version="1.0"?&gt;
   
 &lt;RDF xmlns="<span class="plain">http://www.w3.org/1999/02/22-rdf-syntax-ns#</span>"
    xmlns:em="<span class="plain">http://www.mozilla.org/2004/em-rdf#</span>"&gt;
   
   &lt;Description about="<span class="plain">urn:mozilla:install-manifest</span>"&gt;
   
   &lt;em:id&gt;<span class="plain">status-bar-sample-1@example.com</span>&lt;/em:id&gt;
   &lt;em:version&gt;1.0&lt;/em:version&gt;
   &lt;em:type&gt;2&lt;/em:type&gt;
     
   &lt;!-- Front End Metadata --&gt;
   
   &lt;em:name&gt;Status Bar Sample 1&lt;/em:name&gt;
   &lt;em:description&gt;Sample static status bar panel&lt;/em:name&gt;
   &lt;em:creator&gt;My Name&lt;/em:creator&gt;"
   &lt;em:homepageURL&gt;<span class="plain">http://developer.mozilla.org/en/docs/Creating_a_status_bar_extension</span>&lt;/em:homepageURL&gt;
   
   &lt;!-- Describe the Firefox versions we support --&gt;
   
   &lt;em:targetApplication&gt;
     &lt;Description&gt;
     &lt;em:id&gt;{ec8030f7-c20a-464f-9b0e-13a3a9e97384}&lt;/em:id&gt;
     &lt;em:minVersion&gt;1.5&lt;/em:minVersion&gt;
     &lt;em:maxVersion&gt;2.0.0.*&lt;/em:maxVersion&gt;
     &lt;/Description&gt;
   &lt;/em:targetApplication&gt;
   
   &lt;/Description&gt;
   
 &lt;/RDF&gt;
</pre>
<p>Let's take a look at some key parts of the manifest.
</p>
<h3 name="Extension_identification_information">Extension identification information</h3>
<p>Certain information is needed so Firefox can uniquely identify your extension.  In this sample, these fields are:
</p>
<table class="standard-table">

<tbody><tr>
<td class="header">Property name
</td><td class="header">Description
</td></tr>

<tr>
<td>id
</td><td>A unique identification string.  Before Firefox 1.5, this was a <a href="en/Generating_GUIDs">GUID</a>.  Starting with Firefox 1.5, however, you should use a string in the form <i>extension-name</i>@<i>creator-domain</i>.
</td></tr>

<tr>
<td>version
</td><td>The extension's version number.
</td></tr>

<tr>
<td>type
</td><td>The addon type.  For extensions, this is 2.
</td></tr>
</tbody></table>
<h3 name="Human-readable_information">Human-readable information</h3>
<p>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:
</p>
<table class="standard-table">


<tbody><tr>
<td class="header">Property name
</td><td class="header">Description
</td></tr>

<tr>
<td>em:name
</td><td>The extension's name.  This name is displayed in the Extensions window.
</td></tr>

<tr>
<td>em:description
</td><td>A short, one-line description of the extension.  This text is also displayed in the Extensions window.
</td></tr>

<tr>
<td>em:creator
</td><td>The author's name.
</td></tr>

<tr>
<td>homepageURL
</td><td>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.
</td></tr>
</tbody></table>
<h3 name="Target_application_information">Target application information</h3>
<p>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.
</p><p>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.
</p><p>The target application information is contained within the <code>em:targetApplication</code> <code>Description</code> block.
</p>
<table class="standard-table">

<tbody><tr>
<td class="header">Property name
</td><td class="header">Description
</td></tr>

<tr>
<td>id
</td><td>An ID indicating the target application.  "{ec8030f7-c20a-464f-9b0e-13a3a9e97384}" is a GUID that uniquely identifies Firefox as the target.
</td></tr>

<tr>
<td>minVersion
</td><td>The oldest version of the target application on which the extension is supported.
</td></tr>

<tr>
<td>maxVersion
</td><td>The most recent version of the target application on which the extension is known to work.
</td></tr>
</tbody></table>
<p>For details on the format of an install manifest, read the <a href="en/Install_Manifests">Install Manifests</a> section.
</p>
<h2 name="The_chrome_manifest">The chrome manifest</h2>
<p>The chrome manifest is a file that tells the target application where to look for the chrome package for your extension.  The <a href="en/Chrome">chrome</a> 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.
</p><p>The chrome manifest file, <tt>chrome.manifest</tt>, for the sample follows.
</p>
<pre class="eval"> content status-bar-sample-1 chrome/content/
 
 # Firefox
 overlay	<span class="plain">chrome://browser/content/browser.xul</span> <span class="plain">chrome://status-bar-sample-1/content/status-bar-sample-1.xul</span>
</pre>
<p>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.
</p><p>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.
</p><p>See <a href="en/XUL_Overlays">XUL Overlays</a> for details on how overlays work.  You can also find more details about format of chrome manifests in the <a href="en/Chrome_Manifest">Chrome Manifest</a> section.
</p>
<h2 name="The_XUL_overlay">The XUL overlay</h2>
<p>The XUL overlay file contains the XUL description of the user interface we want to add to Firefox.  Our overlay file, <tt>status-bar-sample-1.xul</tt>, looks like this:
</p>
<pre class="eval"> &lt;?xml version="1.0" encoding="UTF-8"?&gt;
 
 &lt;!DOCTYPE overlay &gt;
 &lt;overlay id="status-bar-sample-1-overlay"
          xmlns="<span class="plain">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</span>"&gt;
 
 &lt;!-- Firefox --&gt;
 &lt;statusbar id="status-bar"&gt;
   &lt;statusbarpanel id="status-bar-sample-1"
     label="Hello World"
     tooltiptext="Sample status bar item"
   /&gt;
 &lt;/statusbar&gt;
 
 &lt;/overlay&gt;
</pre>
<p>The first order of business in the <tt>status-bar-sample-1.xul</tt> 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:
</p>
<pre class="eval">&lt;overlay id="status-bar-sample-1-overlay"
  xmlns="<span class="plain">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</span>"&gt;
</pre>
<p>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 <code>statusbar</code> named "status-bar" -- which is the Firefox browser window's status bar -- a new <code>statusbarpanel</code> object we call "status-bar-sample-1".
</p><p>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.
</p>
<h2 name="Trying_it_out">Trying it out</h2>
<p>To test your extension, drop the folder into the extensions folder in your <a class="external" href="http://kb.mozillazine.org/Profile_folder">Profile Folder</a>.  Then restart Firefox, and you should see the extension in the status bar.
</p>
<center>
<p><img alt="Image:status bar sample 1.png" src="File:en/Media_Gallery/Status_bar_sample_1.png">
</p>
</center>
<p>{{template.Next("Creating a dynamic status bar extension")}}
</p>{{ wiki.languages( { "pl": "pl/Tworzenie_rozszerzenia_paska_stanu" } ) }}
Revert to this revision