DojoFirebugExtension Reference Guide

From FirebugWiki

Revision as of 21:08, 19 November 2011

Intro

Are you a dojo app developer? How many times did you find that having the chance to debug the HTML, DOM and also the javascript of your page was *great*, but at the same time you wanted to have a faster access to dojo specifics? Exactly...That was one of the motivations behind this Dojo Firebug extension.

The idea of this extension is to provide easy access to some dojo concepts. Coding and debugging time can be reduced by having features to monitor dijits, access higher-level dojo concepts and specific dojo properties (instead of just DOM properties), see the available connections and subscriptions and be able to set breakpoints on those.

With this extension you can:

• View all the widgets registered in the dijit registry (as a Tree or as a plain list)
  • View their properties. For each widget you can also switch the view between "dojo specific properties" and "classic DOM properties". For example, whether the widget's startup() method was already invoked or not.
  • Highlight dojo widgets in the web page (when you mouse-over them).
  • View detached widgets (widgets not yet attached to page).
• View information about the dojo version, dojo-config object, url modules of the loaded page, and the total number of widgets, connections and subscriptions (these numbers are automatically refreshed in the extension UI...useful to detect leaks).
• View all available connections and subscriptions (global to the app), and also connections and subscriptions associated to a "selected" object. You can filter the connections table to find some specific ones to debug.
• Set breakpoints to connections: in the connections's event, in the target method, and in the line where the connection was created (i.e. dojo.connect)
• Set breakpoints to subscriptions: in the target method and where the subscription was created.
• Open documentation associated to a dojo object.

The extension is integrated with the Firebug inspector. You can right-click on a dijit element in the web page and it will be selected/inspected in the extension panels. You can also click the Firebug's inspect button from inside the extension panel and inspect only the dojo elements from your page.

Also, several new visual representations were added to Firebug to better identify dojo objects in Firebug panels.

The Dojo Firebug Extension started as an internal IBM initiative to help IBMers working with Dojo.

Download

The Dojo Firebug Extension is available from in the dojofirebugextension folder at getfirebug.com. Pick version number folder to match your version of Firebug.

Tested platforms, Installation and other info

Latest version from 1.8 download folder was tested with Firefox 6.0.1 and 7, plus Firebug 1.8.2 in Linux and Windows.

Latest version from 1.7 download folder was tested with Firefox 4.0 and 4.0.1 , and Firefox 5 in Windows with Firebug 1.7.x.

• Compatibility table:
  • Firefox 3.6 with Firebug 1.7.3 . Dojo Extension v1.0.x from 1.7 folder
  • Firefox 4.0 with Firebug 1.7.3 . Dojo Extension v1.0.x from 1.7 folder
  • Firefox 5.0 with Firebug 1.7.3 . Dojo Extension v1.0.x from 1.7 folder
  • Firefox 5.0 with Firebug 1.8.x . Dojo extension v1.1+ from 1.8 folder
  • Firefox 6.0 with Firebug 1.8.x . Dojo extension v1.1+ from 1.8 folder
  • Firefox 7.0 with Firebug 1.8.x . Dojo extension v1.1+ from 1.8 folder

• 10/04/2011 Note: (FF 6/7 and Firebug 1.8.x) from time to time the dojo panel isn't displayed by Firebug (we won't know why yet) . To solve this , you need to disable the dojo extension (from the FF addons manager) , restart FF . Then re-enable the extension and restart FF one more time. That's all.

• 07/07/2011 Note: if you previously installed the "dojofirebugextension-1.0.xpi" from this server and now you get a "not compatible with Firefox 5" error, please remove the extension and install it again (from http://getfirebug.com/releases/dojofirebugextension/1.7/dojofirebugextension-1.0.xpi). We updated the compatibility support but kept xpi version number.

• You need to enable Console and Script panels if you want this extension to work properly.
• You may probably want to create an extra profile in Firefox to try this extension (more info here http://www.howtogeek.com/howto/internet/firefox/use-multiple-firefox-profiles-at-the-same-time/ and here http://support.mozilla.com/en-US/kb/Managing-profiles).
• The latest version of the extension will not work with Firebug 1.6.x
  • if you want a version for Firebug 1.6.x please go to https://getfirebug.com/releases/dojofirebugextension/1.6/ , but keep in mind that version has fewer features. The recommended combination in this case is: FF 3.6.x + Firebug 1.6.x + this extension

• This extension WILL NOT WORK with Firebug 1.5.x

Main Panel

In this panel you can access:

• All Widgets : displays all available widgets in dijit registry. You can see the widgets as a Tree or as a plain list, by changing a setting in the main menu of the extension panel.
• All Connections: displays all registered connections as a Table.
• All Subscriptions: displays existent subscriptions (as a Tree).

There are also some useful side panels at the right:

• Info side panel
• Connections and Subscriptions for a "selected" object
• DOM and HTML panels to show lower level info of the "selected" object

Widgets

The widgets view displays the available widgets in dijit registry. By default they are displayed in a Tree according to how they are placed in the web page. If you move the mouse pointer over the widgets, you will see them highlighted in the page.

In the following 2 screnshots you will see a widget selected (in the extension panel) and the same widget highlighted in the web page.

Widgets as list

There is also an option to display the widgets as a list (instead of tree). You can switch it in the extension's main menu.

Diplaying properties

Widgets can display highlevel info related to dojo, or you can just see all their DOM properties (you can change this behavior using the toggle button at the right of each widget)

Other widget options

This is how detached widgets look like in the panel:

Documentation links available for widgets:

Connections panel

This extension collects information about connections made by dojo.connect and widget.connect methods. They are displayed in a table with the following columns: Object, Event, Context, and Method (trying to follow the names of the arguments of the dojo.connect method).

Filtering connections

You can enter a filtering criteria to display connections .

Important: using a "count" filter with a small value will improve performance of the connections panel (e.g. Begin = 0, End = 50 , or Begin = -50, End = 0 if you want the last 50 connections created).

When writing a filter, you can use 3 fields: "Begin" , "End" , and "Filter" . Begin and End fields follow the rules from Array's slice method (https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/slice).

1. Begin: starting index (0 based) . You can use negative indexes too.

2. End : zero-based index at which to end filtering connections (not including "end"). You can use negative indexes too.

3. Filter: a filtering query . It currrently accepts 2 syntaxes:

3.1. You can write a simple string (you can also enter perl regex as well as use a simpler form with * and ? wildcards) , that will be compared (regexp match) against connection's event and method attributes. For example:

 dojo*

3.2. You can also write a filtering query following the rules from dojo.data.ItemFileReadStore , i.e. a query object (JSON notation) to filter by several fields at once. Some examples:

  { event: '*dojo*' }

  { object: '*button*' , method: 'onClick' }

Picture 1: simpler syntax

Picture 2: query object . For this specific example the query was:

  { context: '*menu*', method:'from*'}

Subscriptions panel

This view displays information about topics and subscriptions. Each flag represent a topic with its name in red. Each children represent the interested object and the method that will be executed.

Side panels

Info

Display information about dojo loaded in the web page

Connections

Subscriptions

Widget Properties

Integration of Firebug inspector and the dojo extension - Inspect in Dojo Panel

You can inspect any dijit by right-clicking in web page and choosing Inpect in Dojo panel

Also, you can use the Firebug Inspector tool (the arrow icon at the left) and choose any dijit in the web page. When you use this option, dijits in web page will display a green border when mouseover.

Breakpoints

The extension allows you to add breakpoints to connections and subscriptions. You can:

• Break on Target execution
• Break on Event execution
• Break on connect place (or subscribe place) . The place where the dojo.connect was executed to create the connection (IMPORTANT:see performance note below).

Performance note: app loading time will be increased 4X when "Breakpoint on connect/subscribe place" is enabled.

The following pictures show the idea:

Picture 1 and 2: context menu for connections and those items checked

Picture 3: Breakpoints listed in Firebug's Script panel (breakpoints sidepanel)

Pictures 4 and 5: source code with breakpoints

Tip: Debugging dojo source with Firebug 1.7 and Firefox 4

Due to a problem with FF 4, when using a source build of dojo with FF 4 you won't be able to see filenames in the files dropdown list of Firebug's Script panel. Probably you will see entries like this:

 dojo.js/eval:eval(...

or like this:

But if you change 1 line in the dojo[eval] implementation you'll be able to see and debug dojo files again:

You need to change the following file:

 dojo/_base/_loader/bootstrap.js

and in the eval function implementation, replace this line:

  return d.global.eval ? d.global.eval(scriptFragment) : eval(scriptFragment); 	// Object

by this one:

  return eval(scriptFragment); 	// Object

ending in something like this:

  	dojo["eval"] = function(/*String*/ scriptFragment){
		//	summary:
		//		A legacy method created for use exclusively by internal Dojo methods. Do not use
		//		this method directly, the behavior of this eval will differ from the normal
		//		browser eval.
		//	description:
		//		Placed in a separate function to minimize size of trapped
		//		exceptions. Calling eval() directly from some other scope may
		//		complicate tracebacks on some platforms.
		//	returns:
		//		The result of the evaluation. Often `undefined`
 
		//return d.global.eval ? d.global.eval(scriptFragment) : eval(scriptFragment); 	// Object		
		return eval(scriptFragment); 	// Object
	}

Known issues

This is the list of known issues we know about of :-)

• Does not work with Firebug in a separate window
• You can use this extension with Firefox 3.6 (and Firebug 1.7!) but JS objects asociated to connections/subscriptions will contain another DOM property called x_dojoExtHashCode_. This may affect your application if it's coded using some foreach var in object loops.
  • you can avoid that property by setting the Firefox preference extensions.firebug.dojofirebugextension.useHashCodes to false. (go to about:config page to set preferences) .
  • Remember: you do not need to change anything if using FF 4

Authors

• Patricio Reyna Almandos (IBM Argentina)
• Fernando Gomez (IBM Argentina)