Building an extension

  • Revision slug: Building_an_Extension
  • Revision title: Building an extension
  • Revision id: 33250
  • Created:
  • Creator: Ben
  • Is current revision? No
  • Comment /* Chrome URIs */

Revision Content

Introduction

This tutorial will take you through the steps required to build a very basic extension - one which adds a status bar panel to the Firefox browser containing the text "Hello, World!"

Note This tutorial is about building extensions for Firefox 1.5. Other tutorials exist for building extensions for earlier versions of Firefox.

Setting up the Development Environment

Extensions are packaged and distributed in ZIP files with the <tt>xpi</tt> (pronounced “zippy”) extension. The layout of content within the XPI file is like so:

extension.xpi:
              /chrome/chromeFiles/
              /components/
              /defaults/
              /defaults/preferences/
              chrome.manifest
              install.rdf

Because of this, it is easiest if we lay out our source files in a similar fashion, unless you want to write some sort of Makefile or shell script to package and zip all of your files. Even if you are prepared to do that, testing is much simpler if you lay out your files like this because of a feature of Firefox 1.5's Addon System.

So let's get started. Create a folder for your extension somewhere on your hard disk, e.g. <tt>c:\extensions\myExtension\</tt>. Inside this folder create another folder called <tt>chrome</tt>, inside the <tt>chrome</tt> folder create a folder called <tt>chromeFiles</tt> and inside the <tt>chromeFiles</tt> folder create a folder called <tt>content</tt>.

Inside the root of your extension folder, alongside the <tt>chrome</tt> folder create two new empty text files, one called <tt>chrome.manifest</tt> and the other called <tt>install.rdf</tt>.

Create the Install Manifest

Extending the Browser with XUL

Firefox's user interface is written in XUL and JavaScript. XUL is an XML grammar that provides user interface widgets like buttons, menus, toolbars, trees etc. User actions are bound to functionality using JavaScript.

To extend the browser, we modify parts of the browser UI by adding or modifying widgets. We add widgets by inserting new XUL DOM elements into the browser window, and modify them by using script and attaching event handlers.

The browser is implemented in a XUL file called <tt>browser.xul</tt>. In browser.xul we can find the status bar, which looks something like this:

<statusbar id="status-bar">
 ... <statusbarpanel>s ...
</statusbar>

<tt><statusbar id="status-bar"></tt> is a "merge point" for a XUL Overlay.

XUL Overlays

XUL Overlays are a way of attaching other UI widgets to a XUL document at run time. A XUL Overlay is a .xul file that specifies XUL fragments to insert at specific merge points within a "master" document. These fragments can specify widgets to be insreted, removed, or modified.

Example XUL Overlay Document

<?xml version="1.0">
<overlay id="sample" 
         xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
 <statusbar id="status-bar">
  <statusbarpanel id="my-panel" label="Hello, World"/>
 </statusbar>
</overlay>

The <tt><statusbarpanel></tt> called <tt>status-bar</tt> specifies the "merge point" within the browser window that we want to attach to.

The <tt><statusbarpanel></tt> child is a new widget that we want to insert within the merge point.

Take this sample code above and save it into a file called <tt>sample.xul</tt> inside the <tt>chrome/chromeFiles/content</tt> folder you created.

For more information about merging widgets and modifying user interface using Overlays, see below.

Chrome URIs

XUL files are part of "Chrome Packages" - bundles of user interface components which are loaded via <tt>chrome://</tt> URIs. Rather than load the browser from disk using a <tt>file://</tt> URI (since the location of Firefox on the system can change from platform to platform and system to system), Mozilla developers came up with a solution for creating URIs to XUL content that the installed application knows about.

The browser is: <tt>chrome://browser/content/browser.xul</tt> Try typing this URL into the location bar in Firefox!

Chrome URIs consist of several components:

  • Firstly, the URI scheme (<tt>chrome</tt>) which tells Firefox's networking library that this is a Chrome URI and that content being loaded from one needs to be handled specially.
  • Secondly, a package name (in the example above, <tt>browser</tt>) which identifies the bundle of user interface components. This should be as unique to your application as possible to avoid collisions between extensions.
  • Thirdly, the type of data being requested. There are three types: <tt>content</tt> (XUL, JavaScript, XML XBL bindings etc that form the structure and behavior of an application UI), <tt>locale</tt> (DTD, .properties files etc that contain strings for the UI's localization), and <tt>skin</tt> (CSS and images that form the theme of the UI)
  • Finally, a file name to load.

So, <tt>chrome://foo/skin/bar.png</tt> loads the file <tt>bar.png</tt> from <tt>foo</tt>'s theme <tt>skin</tt> section.

When you load content using a Chrome URI, Firefox uses the Chrome Registry to translate these URIs into the actual source files on disk (or in JAR packages).

Create a Chrome Manifest

For more information on Chrome Manifests and the properties they support, see the Chrome Manifest Reference.

Review

Test

Package

More on XUL Overlays

Creating New User Interface Components

XPCOM Components

Localizing, Theming

Understanding the Browser

Debugging Extensions

Extension Versioning and Compatibility

Update and Compatibility

References

Revision Source

<h4 name="Introduction"> Introduction </h4>
<p>This tutorial will take you through the steps required to build a very basic extension - one which adds a status bar panel to the Firefox browser containing the text "Hello, World!"
</p><p><b>Note</b> This tutorial is about building extensions for Firefox 1.5. Other tutorials exist for building extensions for earlier versions of Firefox. 
</p>
<h4 name="Setting_up_the_Development_Environment"> Setting up the Development Environment </h4>
<p>Extensions are packaged and distributed in ZIP files with the <tt>xpi</tt> (<i>pronounced “zippy”</i>) extension. The layout of content within the XPI file is like so:
</p>
<pre class="eval">extension.xpi:
              /chrome/chromeFiles/
              /components/
              /defaults/
              /defaults/preferences/
              chrome.manifest
              install.rdf
</pre>
<p>Because of this, it is easiest if we lay out our source files in a similar fashion, unless you want to write some sort of Makefile or shell script to package and zip all of your files. Even if you are prepared to do that, testing is much simpler if you lay out your files like this because of a feature of Firefox 1.5's Addon System. 
</p><p>So let's get started. Create a folder for your extension somewhere on your hard disk, e.g. <tt>c:\extensions\myExtension\</tt>. Inside this folder create another folder called <tt>chrome</tt>, inside the <tt>chrome</tt> folder create a folder called <tt>chromeFiles</tt> and inside the <tt>chromeFiles</tt> folder create a folder called <tt>content</tt>. 
</p><p>Inside the root of your extension folder, alongside the <tt>chrome</tt> folder create two new empty text files, one called <tt>chrome.manifest</tt> and the other called <tt>install.rdf</tt>.
</p>
<h4 name="Create_the_Install_Manifest"> Create the Install Manifest </h4>
<h4 name="Extending_the_Browser_with_XUL"> Extending the Browser with XUL </h4>
<p>Firefox's user interface is written in XUL and JavaScript. <a href="en/XUL">XUL</a> is an XML grammar that provides user interface widgets like buttons, menus, toolbars, trees etc. User actions are bound to functionality using JavaScript. 
</p><p>To extend the browser, we modify parts of the browser UI by adding or modifying widgets. We add widgets by inserting new XUL DOM elements into the browser window, and modify them by using script and attaching event handlers. 
</p><p>The browser is implemented in a XUL file called <tt>browser.xul</tt>. In browser.xul we can find the status bar, which looks something like this:
</p>
<pre class="eval">&lt;statusbar id="status-bar"&gt;
 ... &lt;statusbarpanel&gt;s ...
&lt;/statusbar&gt;
</pre>
<p><tt>&lt;statusbar id="status-bar"&gt;</tt> is a "merge point" for a XUL Overlay.
</p>
<h5 name="XUL_Overlays"> XUL Overlays </h5>
<p>XUL Overlays are a way of attaching other UI widgets to a XUL document at run time. A XUL Overlay is a .xul file that specifies XUL fragments to insert at specific merge points within a "master" document. These fragments can specify widgets to be insreted, removed, or modified. 
</p><p><b>Example XUL Overlay Document</b>
</p>
<pre class="eval">&lt;?xml version="1.0"&gt;
&lt;overlay id="sample" 
         xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"&gt;
 &lt;statusbar id="<b>status-bar</b>"&gt;
  &lt;statusbarpanel id="my-panel" label="Hello, World"/&gt;
 &lt;/statusbar&gt;
&lt;/overlay&gt;
</pre>
<p>The <tt>&lt;statusbarpanel&gt;</tt> called <tt><b>status-bar</b></tt> specifies the "merge point" within the browser window that we want to attach to. 
</p><p>The <tt>&lt;statusbarpanel&gt;</tt> child is a new widget that we want to insert within the merge point. 
</p><p>Take this sample code above and save it into a file called <tt><b>sample.xul</b></tt> inside the <tt>chrome/chromeFiles/content</tt> folder you created.
</p><p>For more information about merging widgets and modifying user interface using Overlays, see below.
</p>
<h4 name="Chrome_URIs"> Chrome URIs </h4>
<p>XUL files are part of "Chrome Packages" - bundles of user interface components which are loaded via <tt>chrome://</tt> URIs. Rather than load the browser from disk using a <tt>file://</tt> URI (since the location of Firefox on the system can change from platform to platform and system to system), Mozilla developers came up with a solution for creating URIs to XUL content that the installed application knows about. 
</p><p>The browser is: <tt>chrome://browser/content/browser.xul</tt> Try typing this URL into the location bar in Firefox!
</p><p>Chrome URIs consist of several components:
</p>
<ul><li> Firstly, the <b>URI scheme</b> (<tt>chrome</tt>) which tells Firefox's networking library that this is a Chrome URI and that content being loaded from one needs to be handled specially. 
</li><li> Secondly, a package name (in the example above, <tt><b>browser</b></tt>) which identifies the bundle of user interface components. This should be as unique to your application as possible to avoid collisions between extensions. 
</li><li> Thirdly, the type of data being requested. There are three types: <tt>content</tt> (XUL, JavaScript, XML XBL bindings etc that form the structure and behavior of an application UI), <tt>locale</tt> (DTD, .properties files etc that contain strings for the UI's localization), and <tt>skin</tt> (CSS and images that form the theme of the UI)
</li><li> Finally, a file name to load. 
</li></ul>
<p>So, <tt>chrome://foo/skin/bar.png</tt> loads the file <tt>bar.png</tt> from <tt>foo</tt>'s theme <tt>skin</tt> section. 
</p><p>When you load content using a Chrome URI, Firefox uses the Chrome Registry to translate these URIs into the actual source files on disk (or in JAR packages).
</p>
<h4 name="Create_a_Chrome_Manifest"> Create a Chrome Manifest </h4>
<p>For more information on Chrome Manifests and the properties they support, see the <a href="en/Chrome_Manifest">Chrome Manifest</a> Reference.
</p>
<h4 name="Review"> Review </h4>
<h4 name="Test"> Test </h4>
<h4 name="Package"> Package </h4>
<h4 name="More_on_XUL_Overlays"> More on XUL Overlays </h4>
<h4 name="Creating_New_User_Interface_Components"> Creating New User Interface Components </h4>
<h4 name="XPCOM_Components"> XPCOM Components </h4>
<h4 name="Localizing.2C_Theming"> Localizing, Theming </h4>
<h4 name="Understanding_the_Browser"> Understanding the Browser </h4>
<h4 name="Debugging_Extensions"> Debugging Extensions </h4>
<h4 name="Extension_Versioning_and_Compatibility"> Extension Versioning and Compatibility </h4>
<h4 name="Update_and_Compatibility"> Update and Compatibility </h4>
<h4 name="References"> References </h4>
Revert to this revision