Firebug 1.10 Extension Architecture

From FirebugWiki
Revision as of 09:48, 9 February 2012 by Honza (Talk | contribs)

Jump to: navigation, search

Firebug 1.10 introduces support for bootstrapped extensions and also new APIs for extensions. This page is intended to document these new APIs.


Firebug 1.10 supports three concepts that can be used when developing an extension:

  • XUL Based Extensions
  • Bootstrapped Extensions
  • AMD Extensions

XUL Based Extensions

XUL represents an old school technique and Firebug has always supported this ways of extending. The main difference from the bootstrapped extensions is that you need to restart the browser whenever your extension is installed or uninstalled.

Important thing related to XUL based extension is to understand scopes. First see the next diagram.


There are two scopes that are relevant to extension development.

  • Browser Window: use this scope when overlaying browser UI. Your extension might want to append new button into Firefox toolbar or create, create a new menu items, etc.
  • Firebug UI: this is the scope mostly used by Firebug extension, use it whenever you want to extend Firebug. Your extension might want to crate a new Firebug panel, etc.

Note that Firebug 1.10 introduces a new feature called Delayed Load. This means that overlays applied to chrome://firebug/content/firebugOverlay.xul are loaded the first time the Firebug UI is actually opened by the user. This way loading doesn't slow down Firefox start up time.

Also, the global Firebug object is available since Firefox start even if Firebug is not fully loaded yet, but contains only a small set of APIs.

Bootstrapped Extensions

Support for bootstrapped extensions has been introduced in Firebug 1.10. There are (at least) three entities you'll be dealing with when developing basic structure of a bootstrapped (restart-less) extension.

  • bootstrap.js - Every Firefox bootstrapped extension needs to provide a bootstrap.js file that is expected to implement basic functions like: install, uninstall, startup, shutdown. In case of a Firebug extension further functions like: firebugStartup, firebugFrameLoad, etc. are expected. These functions/callbacks are automatically executed to allow proper initialization/shutdown of the extension.
  • FirebugLoader - is a component resource://firebug/loader.js that distributes events to all Firebug bootstrapped extensions.
  • Firebug - The Firebug object

See following sequence diagram:


  • When Firebug itself is loaded (bootstrapped), FirebugLoader fires an firebugStartup event. This is the moment when the extension can register itself as a listener for further events by calling registerBootstrappScope function.
  • Later when the user requires Firebug for the first time, the firebugFrameLoad callback is executed. The callback has one parameter the Firebug object. This is also the time when overlays applied to chrome://firebug/content/firebugOverlay.xul are loaded.
  • If the extension is using AMD, it can register itself as by calling Firebug.registerExtension (see further AMD Extensions chapter)

Following callbacks can be implemented in bootstrap.js file:

Firefox API:

  • install()
  • uninstall()
  • startup()
  • shutdown()

Firebug APIs

  • firebugStartup() - called when Firebug is bootstrapped
  • firebugShutdown() - called when Firebug is uninstalled
  • topWindowLoad(win) - called when a new browser window is opened
  • topWindowUnload(win) - called when an existing browser window is closed
  • firebugFrameLoad(Firebug) - called when Firebug UI is loaded into an existing browser window
  • firebugFrameUnload(Firebug) - called when Firebug UI is unloaded from an existing browser window

AMD Extensions

This technique (Asynchronous Module Definition) is related to how code of your extension is organized. It can be used together with XUL based or bootstrapped extensions. Using AMD in your extension is recommended since it helps to organizes your code into modules, properly maintain dependencies and use external modules such as those provided by Firebug framework.