Shortest Tutorial for Firefox Extension/Toolbar Development!

About This Tutorial: From long time I wanted to write this but was always running out of time as the topic is complicated and too long! I always like to come-up with simple ways of doing geekish things as this Devils Workshop have great variance in its audience. So writing a post for all is always cumbersome but still lets see how it goes.

Who Should Read This: This is for anyone who is new to firefox extension development. More accurately for the geeks who haven’t coded any extension for firefox yet! This is just to build foundation, to kick-start yourself!

About Example Covered: The example covered with this tutorial is a toolbar with just one feature: Google Search! And lets call it: GoogBar! (You can Download Source here)

Following Points are Covered: Firefox extension development can easily swamp many books (with scary volume numbers) we will try to cover following points…

• Section 0: Prerequisites, Tools & References
• Section 1: Basic File Structure Layout
• Section 2: Creating Metadata – Dealing with Important files
• Section 3: Creating Graphical User Interface – GUI
• Section 4: Implementing Backend functions
• Section 5: Packaging Extension for distribution!
• Section 6: Installing & Testing Your Extension!

Section 0: Prerequisites, Tools & References!

Prerequisites: Little knowledge of HTML/XHTML, XML, JavaScript, and CSS.

Tools: Any text-editor which supports HTML/Javascript/CSS syntax-highlighting will be great. I use vi/gedit (on Linux) and notepad (on Windows)

References: I started with tutorial at BornGeeK and still find it useful. In fact its greatness will reflect throughout this post. Still you may find these useful

• MozillaZine Extension development Article
• MozillaZine Extension Development Forum
• XUL Planet Element Reference
• Firefox Toolbar Tutorial by Born Geek
• Firefox Toolbar Tutorial by Extend Firefox

Section 1: Basic File Structure Layout

Lets go other way round – Outside-In!

Firefox extensions filename ends with xpi extension. For time being assume xpi = zip. In fact xpi is just zip archive! So what this archive contains?

It will contain atleast: 2 files – install.rdf & chrome.manifest + 1 folder – usually named chrome!

Firefox extensions require a specific internal file structure. To ensure this few files/folders will always have fixed place while optional files/components have little freedom to move around. Lets move ahead with an example extension: GoogBar so as keep track of extension development! Lets start by creating a directory – GoogBar and other files/folder structure under it as shown below…

+- GoogBar/
    +- content/
    +- install.rdf
    +- chrome.manifest

install.rdf & chrome.manifest are just plain-text file so create two empty text files and rename them to install.rdf & chrome.manifest.

Important Note: Be careful while renaming files on windows as extension part often remains unchanged. Make sure to rename something like new.txt to install.rdf and not install.rdf.txt!

Section 2: Creating Metadata – Dealing with Important files

Metadata means data about data! All the metadata is stored in install.rdf & chrome.manifest.

A. install.rdf file

This is XML file. It contains metadata identifying the addon, providing information about who created it, where more information can be found about it, which versions of what applications it is compatible with, how it should be updated, and so on. We have already created empty install.rdf file. Its time to fill it up!

+- GoogBar/
    +- content/
    +- install.rdf
    +- chrome.manifest

Given below is sample installer manifest. Copy it to your install.rdf file and edit highlighted fields!

<?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">
<!-- Required Items -->
<em:id>[email protected]</em:id>
<em:name>Extension's Name</em:name>
<em:version>1.0</em:version>

<em:targetApplication>
     <Description>
         <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
         <em:minVersion>1.5</em:minVersion>
         <em:maxVersion>3.0.*</em:maxVersion>
     </Description>
</em:targetApplication>

<!-- Optional Items -->
<em:creator>Your Name</em:creator>
<em:description>A description of the extension</em:description>
<em:homepageURL>http://www.yoursite.com/</em:homepageURL>
</Description>
</RDF>

Explanation of Highlighted Fields:

[email protected]: This must be unique as this is id of your extension. So make sure you chose an extension/domain name pair which is not in use by others! Ex. [email protected] (Note: You do not need to purchase a domain to make this unique! Use any domain like yourfullname.com or microsoft.com (I don’t think they have sportsman spirit to develop anything for firefox)

Extension’s Name: This is name of your extension seen by humans! So use something nice & descriptive!

version: The only point I can tell you about version numbers here is they always goes on increasing with updates. So do not bother about this too much at this point.

targetApplication – minVersion & maxVersion: These are minimum and maximum versions of firefox you are targeting!

Optional Items: I guess all have descriptive name. Also there are more than shown in this example. So keep this tutorial short I am skipping details about this optional items!

Important Note: Do not change value {ec8030f7-c20a-464f-9b0e-13a3a9e97384} in above sample! It is GUID of Firefox!

So GoogBar’s install.rdf will look like…

<?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">
<!-- Required Items -->
<em:id>[email protected]</em:id>
<em:name>GoogBar</em:name>
<em:version>1.0</em:version>

<em:targetApplication>
     <Description>
         <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
         <em:minVersion>1.5</em:minVersion>
         <em:maxVersion>3.0.*</em:maxVersion>
     </Description>
</em:targetApplication>

<!-- Optional Items -->
<em:creator>Rahul Bansal</em:creator>
<em:description>A Firefox toolbar with Google Search facility!</em:description>
<em:homepageURL>http://www.devilsworkshop.org/</em:homepageURL>
</Description>
</RDF>

Additional Resources: http://developer.mozilla.org/en/docs/Install_Manifests

B. chrome.manifest file

A chrome manifest is how we tell Firefox what packages and overlays our extension provides. In simple words it tells firefox what our extension does! Now its time to fill up chrome.manifest

+- GoogBar/
    +- content/
    +- install.rdf
    +- chrome.manifest

Let us again take a look at a sample file. This sample is particularly taken for this tutorial as chrome.manifest may contains lots of other information too! Replace highlighted extensionname with your extension name!

content extensionname content/
overlay chrome://browser/content/browser.xul chrome://extensionname/content/overlay.xul

So final Googbar’s chrome.manifest file will look like

content googbar content/
overlay chrome://browser/content/browser.xul chrome://googbar/content/googbar.xul

Let me give you a little more explanation about above two lines…

Line 1 tells: content (Read Functions) by this extension are in content/ directory! All functions which we will be implementing soon as javascript files will be kept in content/ directory!

Line 2 tells: overlay (Read User Interface) information for this extension is in googbar.xul file in content subdirectory! We will be creating goobar.xul soon! In fact we can create XUL file with any other name!

Additional Resources: http://developer.mozilla.org/en/docs/Chrome_Manifest

Section 3: Creating Graphical User Interface – GUI

Most Firefox extensions have one goal in common: wanting to add or change some graphical element(s) in Firefox. Fortunately adding and modifying GUIs is quite easy. But this ease comes with a dedicated language developed for firefox GUI called XUL (pronounced “zool”). XUL stands for XML User-Interface Language, so if you know XML then I bet you can learn XUL in few minutes!

Enough chit-chat, now its time for creating googbar.xul under content subdirectory! So our tree will look like…

+- GoogBar/
    +- content/
       +- googbar.xul
    +- install.rdf
    +- chrome.manifest

First write (copy) following non-optional XML declaration as it is…

<?xml version="1.0"?>
<overlay id="Scrapper-Overlay"
xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
</overlay>

Then comes script tag! Let me brief first scripts coming into picture. Note the sequence of event!

1. In this XUL file we will be adding a toolbar with one text field and a button.
2. We want some code to be executed when someone press the button.
3. So pressing button should call the code. Now we can write code in
4. • this XUL file itself: OK for small code but bad practice!
   • in separate JS file

At this point we made decision to create a separate JS file but this XUL file should be aware of it so that it can associate buttons with JS file code. For this we will be using script tag! Just paste following code before </overlay> tag.

<script type="application/x-javascript" src="chrome://googbar/content/googbar.js" />

Note googbar.js filename above. We will be creating it soon.

Now time come to create toolbar using following XUL code!

All toolbars in Firefox should live within a toolbox element which gets placed inside the overlay element we created moments ago:

<toolbox id="navigator-toolbox"></toolbox>

We will place toolbar and its component inside the toolbox we just specified. Toolbar is basically row of buttons, text-field & labels. Here comes our toolbar with one label (to show toolbars name), one textbox (to specify search query) & one button (to fire search request):

<toolbar id="GoogBarToolbar" toolbarname="GoogBar Toolbar" >
       <label value="GoogBar Toolbar: "/>
       <textbox id="GoogBarQuery" cols="1" size="50" />
       <toolbarbutton id="GoogBarButton"
         label="Search" oncommand="GoogBarSearch(event)" />
</toolbar>

Some attribute values are important as they might be used from elsewhere. In that regard attribute values to note are:

• GoogBarSearch(event) value in toolbarbutton elements oncommand attribute
• GoogBarQuery value in textbox elements id attribute

We will be shortly using these in our next file googbar.js as we are done with googbar.xul which finally looks like…

<?xml version="1.0"?>
<overlay id="Scrapper-Overlay"
xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"><script type="application/x-javascript" src="chrome://googbar/content/googbar.js" />
<toolbox id="navigator-toolbox">
   <toolbar id="GoogBarToolbar" toolbarname="GoogBar Toolbar" >
       <label value="GoogBar Toolbar: "/>
       <textbox id="GoogBarQuery" cols="1" size="50" />
       <toolbarbutton id="GoogBarButton"
         label="Search" oncommand="GoogBarSearch(event)" />
   </toolbar>
</toolbox>
</overlay>

Important Note: All id/name attribute must be unique as they will be going to global by default! That’s why everytime we need to name something we prefixed it with GoogBar!

Additional Resources:

• http://xulplanet.com
• http://xulplanet.com/references/elemref/

Section 4: Implementing Backend Functions

Let’s now create our JavaScript file – googbar.js in the content directory! That will make our structure look like…

+- GoogBar/
    +- content/
       +- googbar.xul
       +- googbar.js
    +- install.rdf
    +- chrome.manifest

As we highlighted in previous section we will now implement GoogBarSearch(event) function which will make use of GoogBarQuery id. This function will perform following steps:

1. Access user query written in textbox using textbox id GoogBarQuery.
2. Use that value to shoot Google Search Query!

This can be accomplished with following codes. Also thats all googbar.js will have!

function GoogBarSearch(event){
    var query = document.getElementById("GoogBarQuery").value;
    window._content.document.location  = "http://www.google.com/search?q=" + encodeURI(query);
}

Section 5: Packaging Extension for distribution!

Yes we are done! So lets pack the things the way firefox like! Your aim is to create a archive which contains everything inside GoogBar excluding GoogBar itself! Then to make sure that archive has xpi extension!

Packaging on Linux:

• From shell execute zip command with format:

zip <extensionname>.xpi chrome.manifest install.rdf content/* <optional files>

• In our case command needs to be fired is:

zip googbar.xpi chrome.manifest install.rdf content/*

Packaging on Windows:

• Use any zip utility to create a zip file which consists everything inside top-level extension directory! DO NOT include top-level directory itself! OR just select files and folder(s) using control+click and then right-click on selection, select Send To >> compressed (zipped) folder! You will get a zip file with name like googbar.zip or content.zip or something like that!
• Just rename it to googbar.xpi (i.e. extensionname.xpi). Also ensure renaming operation as from Windows explorer you may end up renaming file to something like googbar.xpi.zip!

Thats it! Its time to test our work! 🙂

Section 6: Installing & Testing Your Extension!

Just drag-n-drop googbar.xpi on Firefox. OR Go to Firefox, execute File >> Open (or press ctrl+O) and navigate to location of googbar.xpi and open it up! This will open a pop-up, click Install Now to proceed and restart firefox to complete installation!

After restarting you will see GoogBar below Navigation Toolbar. Also check View >> Toolbars in firefox to confirm it further!

Type something in text-box and press search! DO NOT just type & hit enter as we havent configured text-box to process any keyboard event so you won’t get any result until you press search button! Well that we can easily do by modifying googbar.xul and goobar.js!

If you are feeling cheated by my words Shortest Tutorial then go anywhere on the web and try finding a shorter version of this! 😉

As ususal comments, suggestion, question, etc are all welcome! 🙂

Next part in series – Setting Up Firefox as IDE for Firefox Extension Development

Links: Download Source for Googbar