The lightning fast tutorial to Firefox extensions

A Firefox extension is a component developed by a third party (ie: you) that extends the functionality  in Firefox. This tutorial will show you how to make an extension that adds a menu item when you right-click on an url in a web-page. Easy and lightning fast.

First things first: When making a Firefox extension, you use Javascipt to implement functionality, and Xul (a html-like language) to make all presentation, including menus.

The extension materializes as an .xpi-file, which only is a folder structure with your files that is zipped into a zip-file (the zip-file is renamed to <filename>.xpi).

Prerequieries

You will ofcourse need Firefox, and also a Zip-utility like Winzip.

The folder structure

You must determine a folder structure (which later will be zipped into the .xpi file). For this tutorial we’ll use this simple structure:

MyFirstExtension/
  files/
     browser_overlay.xul
     browser_overlay.js
  install.rdf
  chrome.manifest


For now, create the folders, the files shown here will be made later in the tutorial. Note: When zipping the folder structure into an .xpi-file (at the end of this tutorial),  include the content of the ”MyFirstExtension”-folder, but not the folder itself.

The “Install manifest” file

The install manifest is used “to determine information about an addon as it is being installed”. The file must be called “install.rdf” and be placed at the root of your folder structure. Create an install.rdf-file and put this xml into it:

<!--l version="1.0--> 
<rdf></rdf> xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
 xmlns:em="http://www.mozilla.org/2004/em-rdf#"&gt; 
 <description about="urn:mozilla:install-manifest"></description> 
  <id>MyFirstExtension@mysite.com</id> 
  <version>0.1</version> 
  <type>2</type> 
  <targetapplication> 
   <description></description> 
    <id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</id> 
    <minversion>1.5</minversion> 
    <maxversion>2.0.0.*</maxversion> 
 
  </targetapplication> 
  <name>My first extension</name> 
  <description>A lightning fast extension!</description>

Feel free to change the properties in bold.  More info can be found here.

The ”Chrome registry” file

“Chrome is the set of user interface elements of the application window that are outside of a window’s content area. Toolbars, menu bars, progress bars, and window title bars are all examples of elements that are typically part of the chrome”. These are the parts we want to manipulate.

Make a file named “chrome.manifest” and put it in your root folder. To specify where the content for the package ‘myfirstextension‘ is to be found, write this in your file: 

 content myfirstextension files/


In short this states: For the myfirstextension-extension,  look for content in the files-folder. And thus the rest of our files will be put in the files-folder.

For more info, look here.

Xul overlay – manipulate the menu 

The magic starts with the Xul overlay. An overlay means that you specify that you want to extend (overlay) an existing Xul-file. We wants to add to a menu, so we need to overlay Firefox’ browser.xul. (To find this file, go to <Firefox installdir>\chrome, extract the browser.jar-file with a zip-tool. Then you’ll find it:  content\browser\browser.xul). Here you’ll find all the default menus etc displayed in Firefox.

To overlay that file, write this in your chrome.manifest-file (in one line):
overlay chrome://browser/content/browser.xul chrome://myfirstextension/content/browser_overlay.xul

Here we say that the browser_overlay.xul-file (which we will create next), should extend (overlay) the browser.xul-file.

The Xul-file

notice this entry in Firefox’ browser.xul-file:

<popup id="contentAreaContextMenu"..

This is the item we want to extend. To do this, simply create a browser_overlay.xul-file, and place it in the files-folder. Put this code into that file:

<?xml version="1.0"?>
<overlay id="myfirstextension_overlay”
 xmlns=”http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul”>
 <script type=”application/x-javascript”
  src=”chrome://myfirstextension/content/browser_overlay.js“/>
 <popup id=”contentAreaContextMenu“>
  <menuitem id=”myfirstextensionitem” label=”Hit me!”
    oncommand=”doYourThing(gContextMenu.linkURL);”/>/>
 </popup>
</overlay>

Note: the overlay id (myfirstextension_overlay) must be unique, or firefox will crash at startup (like it did for me once!)

What we do here is to add another menuitem (”myfirstextensionitem”) to the contentAreaContextMenu, which is defined in Firefox’ browser.xul-file. The menuitem calls the javascript-function doYourThing which is to be found in the browser_overlay.js-file (which we will write next). Notice also that we actually has access to objects (in this case: gContextMenu) defined in the file that we overlay.

Javascript for functionality

The last file to the puzzle is the js-file that defines the actual behaviour. Create a file “browser_overlay.js” and put it in the files-folder. Add this to the file:

function doYourThing(url) {
  alert(url);
}


Ok, this doesn’t really do much (except popping up an messagebox with the url), but the point was only to demonstrate how it works. Now feel free to write any js-code you like in that function.

Wrapping and Installing the extension

Now, zip the folder structure into a standard zip-file.  Include the content of the ”MyFirstExtension”-folder, but not the folder itself. Rename the zipfile to MyFirstExtension.xpi.  And last, it can’t be simpler: drag your xpi-file into Firefox, then follow the instructions. It will now be installed, and you can start using your extension. Right-click on an url and you will see your new menu item.

Good luck! 

Tore Vestues