How to build a firebug extension - Part 1 (getting started)

Posted by

firebug-blog-post

Introduction

This is the first of a series of articles on how to build a Firebug extension. A Firebug extension is just a Firefox extension that runs on top of Firebug. An extension usually implements a panel (view-controller) and/or a module (model-controller). It can use interfaces and services from both Firebug and the Mozilla/Firefox platform, giving the developer powerful tools to create extensions that can debug all aspects of a web page.
It assumes that you are familiar with Firebug and have some basic knowledge of standard web technologies. Experience with creating Firefox add-ons is a plus, but not a necessity.

The objective

We will create a Firebug extension that finds all links in the current page and prints them out in a panel. Once you have done this, you should have a basic understanding of Firebug extension development.

Setting up an environment

The first thing we should do is set up an environment. Since we will focus on using bleeding edge stuff we will use Firefox 10 or later, Firebug 1.10 or later, a text editor of your choice and a Zip utility.

Create a new Firefox profile

It is recommended to use a separate Firefox profile for development work since you will likely adjust some settings and make changes that you probably don't want for your regular profile.

  1. Completely close Firefox
  2. Open the terminal
  3. Enter the following: /Applications/Firefox.app/Contents/MacOS/firefox-bin -p
  4. Press return

Windows users can run "firefox.exe -P" from the Start menu / Run prompt

fx-new-profile-dialog1

Click the create profile button. This will start the profile Wizard. For this profile all you should care about is the profile name.
Give the profile a name and click Done.

fx-new-profile-dialog2

Indispensable Tools

Debugging

FBTrace is Firebug's main debugger console where we can trace messages and inspect objects

Automatic testing

FBTest is Firebug's test console which is optimized for the testing of Firebug extensions.

The example extension

Now that the environment is ready we can start downloading the example extension, HelloBootAMD, provided by Firebug. A copy has been prepared here [zip]. The example extension is a good way to start as each section of the code is thoroughly explained with comments.

Once the file is downloaded, unzip it to your preferred development space.

A Firebug extension is just a Firefox extension that happens to work on top of Firebug. Those who are familiar with regular Firefox extension development will probably recognize the file structure.

The most important files here are chrome/content/myModule.js and chrome/content/myPanel.js. These two files contain the actual HelloBootAMD implementation. The other two files are used by Firefox to properly install the extension.
The example demonstrates how to implement a Firebug panel, use preferences and add content to the panel as well as how to localize(l10n) the GUI text.

chrome.manifest

This file maps the extension's directories to chrome URLs which are used internally in Firefox)
Read more about chrome registration here

Eg.: chrome://hellobootamd/content/ maps to chrome/content

install.rdf

The install manifest file. This is used by Firefox to determine information about an add-on as it is being installed.
More detailed info about install manifests can be found here

The em:id, em:version, em:type and em:bootstrap elements comprise the meta information about the extension itself.
Note that the em:id must be globally unique

em:targetApplication contains information about the target product, supported minimum and maximum versions

bootstrap.js

Since we are going to create a bootstrapped extension (this means Firefox does not need to be restarted), Firefox will be looking for the bootstrap.js in the extension's root directory.
This file contains extension lifecycle hooks/callbacks like install, uninstall, startup and shutdown. The functions are automatically executed by Firefox to allow proper initialization/shutdown of the extension.
For Firebug extensions, bootstrap.js will also contain callbacks that are specific for Firebug.

locale directory

This contains standard Firefox localization property files

skins directory

Standard Firefox skin files
Images and CSS resources go here.

defaults directory

Standard Firefox preference files

Point your Firefox extension directory to your extension

The extension directory directly contains Firebug extension files and you can test your code directly from it using a pointer file. This will make testing code changes more efficient.

  1. Locate your development profile directory. ~/Library/Application\ Support/Firefox/profiles/ (Mac). Windows users please see here
  2. Create a new file and give it the same file name as the em:id value found in the install.rdf. In this case "hellobootamd@janodvarko.cz".
  3. The file should only contain the path to where you unzipped the example extension. Eg.: ~/workspaces/firebug-extensions/HelloBootAMD/ (*nix) or C:\workspaces\firebug-extensions\HelloBootAMD\ (Windows)

Save the pointer file.

Run and test

Next time you reboot the browser, you will be prompted about another program that wants to modify Firefox.
Tick the 'Allow this installation' and press 'Continue'.

This message will only be shown the first time the extension is installed and it acts as a guard for extensions that do not originate from the Mozilla extension directory.
If you open the Firebug console, you should see something like this:

bootstrapped-amd

Do some changes

Now, go back to the project code and open the chrome/content/myPanel.js file. If you browse the code you will find this

As you see here, we extended a Firebug panel. Try to change the title property value, save and restart Firefox and see the result.

If you installed the FBTrace tool (see above) you can watch trace messages from the panel and module code (FBTrace.sysout() calls)
Open Tools > Web Developer > Firebug > Open Firebug Tracing

Conclusion

In this article we created an environment, downloaded the Firebug example extension, and learned how to create a pointer file to make the workflow easier.
In the next article we will create a real world extension based on the example extension and learn how to package and distribute and extension.

Comments