Firebug Internals

From FirebugWiki
Revision as of 22:35, 6 November 2009 by Johnjbarton (Talk | contribs) (How are the XUL files used?)

Jump to: navigation, search



Firebug source is available via subversion

Don't use /trunk, its just old code.

The Firebug source is under branches, eg branches/firebug1.5.

  • fbtest/ Firebug test harness
  • tests/content contains the FBTest suite.
  • lite/ Firebug for non-Firefox browsers
  • chromebug/ Debugger for Firebug (and other Firefox extensions)
  • Most of the remaining directories are extensions (to be under extensions/ some day).

Overview of Firebug

Visually Firebug is a tab bar over two panels. The tab bar start with some buttons, then a set of tabs, the search box, and finally more buttons. The tabs select content for the panels; each main panel has a bar across the top, then content below; each main panel can have an optional side panel. The side panel may have tabs.

As a UI system, Firebug is a XUL wrapper around HTML content in the two panels. The XUL content is mostly static or simple lists. The view is controlled by either collapsing elements or filling the lists. The HTML content is all dynamically created from templates called "domplates".

Architecturally Firebug is a Model-Controller-View (MCV) system with the Firefox DOM being the Model and the the XUL/HTML content of Firebug being the View. The Controller, the bulk of the Firebug code, has multiple architectural elements.

Modules and Contexts

Every Web page being debugged by Firebug has exactly one 'context', an object containing all kinds of meta-data about the page. The Web page 'window' object and the context are Firebug 'modules' at each stage of the page's lifetime. Each module examines the page and places information in the context for later use or display. The modules should have no internal state related to any page: all of their state about the page should be in the context.

Every Firefox browser.xul ChromeWindow creates one instance of every module. A typical Firebug extension will implement one module.


Panels are view-controllers, they manage the content in the HTML panels. Panels are created on demand by Firebug. On creation they are given a document and a context; they create one panelNode in the document and render HTML into the panelNode to show information out of the DOM and context data stores.

Every Firefox tab DOM window can cause at most one panel instance. A typical Firebug extension will implement one panel.

The panel area is managed cooperatively by the panels. When a panel is selected, 'show' is called; the panel activates elements of the toolbar above the panel content area. When another panel is selected, 'hide' is called on the to-be-deselected panel; the panel deactivates each element it activated on 'show'.

Reps (representations)

Object displayable in Firebug are mapped into "FirebugReps", system of objects with HTML templates to display their "real objects". For example, FirebugReps.Element is how DOM elements are rendered. The panel operations in firebug.js and chrome.js use the FirebugRep functions to set up generic aspects of the panels, like the status path (bread crumbs) and location list.

In general, panels are selected by either user action or by object. That is, you should avoid selecting a panel explicitly in your code, but rather you should select the object and let Firebug's object negotiation select the panel.


Way under the visible UI are firebug 'components', non-visual code interacting with the entire Firefox application. For example, firebug-service.js is the firebug adapter for Firefox's Javascript Debugging Service jsd.

How are the XUL files used?

  • browserOverlay.xul : puts Firebug into the bottom of the browser window by "overlay" on to Firefox's browser.xul
  • firebug.xul: puts Firebug into its own window.
  • firebugOverlay.xul: overlays browserOverlay.xul or firebug.xul to add placement-independent features by XUL.

Each extension will typically have one XUL overlay file, it should only have enough code to load the script tags of the extension source code.

How are panels created?

Basically follow the pattern of an existing panel.

  • extend Firebug.Panel
  • add methods
  • use 'this.context' for context dependence
  • Add UI to 'this.panelNode' as HTML.
  • Learn about domplate to create the HTML
  • registerPanel

How does debugging work?

See the Chromebug User Guide

How to write a firebug extension?

A Firebug extension is just a Firefox extension that happens to work on top of Firebug.

How to use FBTrace?

  FBTrace.sysout(<string>, object);