Firebug 1.8 API Changes

From FirebugWiki

(Difference between revisions)
Jump to: navigation, search
(Removed Components)
(Module Directory Structure)
 
(14 intermediate revisions not shown)
Line 1: Line 1:
Firebug 1.8 introduces set of API changes that can impact existing Firebug extensions. This page summarizes these changes and offers solution how to fix broken extensions.  
Firebug 1.8 introduces set of API changes that can impact existing Firebug extensions. This page summarizes these changes and offers solution how to fix broken extensions.  
 +
 +
If you have any troubles to convert your extension to be compatible with Firebug 1.8.*, please ask on [http://groups.google.com/group/firebug newsgroups].
== RequireJS and AMD ==
== RequireJS and AMD ==
Firebug source files are no longer loaded using <script> tags placed in a xul overlay (browserOverlay.xul). Firebug 1.8 uses [http://requirejs.org/ RequireJS] and Asynchronous Module Definition [http://wiki.commonjs.org/wiki/Modules/AsynchronousDefinition AMD]. All files (there are still a few exception) follow the AMD syntax now (see an [http://getfirebug.com/wiki/index.php/Firebug_Coding_Style#Example_Module_File_.28AMD.29 example]).
Firebug source files are no longer loaded using <script> tags placed in a xul overlay (browserOverlay.xul). Firebug 1.8 uses [http://requirejs.org/ RequireJS] and Asynchronous Module Definition [http://wiki.commonjs.org/wiki/Modules/AsynchronousDefinition AMD]. All files (there are still a few exception) follow the AMD syntax now (see an [http://getfirebug.com/wiki/index.php/Firebug_Coding_Style#Example_Module_File_.28AMD.29 example]).
 +
 +
== Module Directory Structure ==
 +
Firebug contains implements many AMD modules and these are organized in a directory structure. Every module ID reflects this structure and so it's easier to find appropriate file.
 +
 +
<span style="color:green">Firebug module directory structure is not finished and so it's not recommended to load existing Firebug modules in Firebug extensions. Existing extension concept (based on overlays) is still supported in Firebug 1.8. Support for module-based extensions will be introduced in Firebug 1.9+</span>
 +
 +
But you can take a quick look how a Firebug panel implementation - using AMD syntax - would look like:
 +
 +
You can also explore entire [http://code.google.com/p/fbug/source/browse/#svn%2Fexamples%2Ffirebug1.8%2Fhelloworld HelloWorld] extension designed for Firebug 1.8.
 +
 +
<source lang="javascript">
 +
define([
 +
    "firebug/lib/object",
 +
    "firebug/lib/trace",
 +
],
 +
function(Obj, FBTrace) {
 +
 +
function MyPanel() {}
 +
MyPanel.prototype = Obj.extend(Firebug.Panel,
 +
{
 +
    name: "helloworld",
 +
    title: "Hello World!",
 +
});
 +
 +
Firebug.registerPanel(MyPanel);
 +
return MyPanel;
 +
});
 +
</source>
 +
 +
 +
* The example uses two AMD modules coming from Firebug <code>"firebug/lib/object"</code> and <code>    "firebug/lib/object"</code>.
 +
* The ID (path) of these modules can yet change. Firebug extensions can already use it, but be ready to adapt to new IDs.
 +
* The structure will be finalized in Firebug 1.9+
 +
 +
You can follow the module structure [http://getfirebug.com/wiki/index.php/Firebug_Modules here].
== Globals ==
== Globals ==
Line 10: Line 47:
* FBL still exists
* FBL still exists
* Domplate still exists
* Domplate still exists
 +
 +
Future versions of Firebug will push on loading appropriate modules instead of using globals. The only existing global variable should be <code>Firebug</code>.
 +
 +
Firebug source and Firebug Extension source (at least those which overlays <code>chrome://firebug/content/firebugOverlay.xul</code>) is now executed within a <code>chrome://firebug/content/firebugFrame.xul</code> scope. So, global variables like <code>gBrowser</code> shouldn't be used (they don't exist in the new scope).
 +
 +
* gBrowser -> FBL.getTabBrowser();
 +
 +
== XUL windows ==
 +
This section applies to extensions that creates new XUL windows/dialogs and use Firebug API in them.
 +
 +
Vast majority of Firebug extensions overlays <code>firebugOverlay.xul</code> so, the typical entry in the <i>chrome.manifest</i> (this is still the recommended way) file is following:
 +
 +
<source lang="javascript">
 +
overlay chrome://firebug/content/firebugOverlay.xul        chrome://myext/content/myext.xul
 +
</source>
 +
 +
These extension should have no problem to work with Firebug 1.8 since they are all running in <code>browser.xul</code> scope where all globals are defined by Firebug.
 +
 +
However, those extension that create new XUL windows or dialogs and use any Firebug global variables could face troubles, especially in cases where any of the following files (and others) are included.
 +
 +
<source lang="javascript">
 +
<script type="application/x-javascript" src="chrome://firebug/content/trace.js"/>
 +
<script type="application/x-javascript" src="chrome://firebug/content/xpcom.js"/>
 +
<script type="application/x-javascript" src="chrome://firebug/content/chrome.js"/>
 +
<script type="application/x-javascript" src="chrome://firebug/content/lib.js"/>
 +
<script type="application/x-javascript" src="chrome://firebug/content/domplate.js"/>
 +
<script type="application/x-javascript" src="chrome://firebug/content/firebug.js"/>
 +
</source>
 +
 +
These files use AMD syntax and so, they must be loaded by a loader now. In order to use Firebug globals within another XUL scope you have two options:
 +
 +
* Pass these globals from the browser window (browser.xul) to the XUL window/dialog through [https://developer.mozilla.org/en/Working_with_windows_in_chrome_code#Passing_data_between_windows window arguments]. This is the preferred way.
 +
 +
* Get an existing browser window and access Firebug in it.
 +
 +
Window arguments:
 +
 +
<source lang="javascript">
 +
var params = {
 +
  Firebug: Firebug,
 +
  FBL: FBL
 +
};
 +
 +
// This is how you open a dialog and pass parameters to it.
 +
var parent = context.chrome.window;
 +
parent.openDialog("chrome://myext/content/myextwindow.xul",
 +
  "_blank", "chrome,centerscreen,resizable=yes,modal=yes",
 +
  params);
 +
 +
// This is how you can get the parameters in onload of the XUL window
 +
var params = window.arguments[0];
 +
var Firebug = params.Firebug;
 +
var FBL = params.FBL;
 +
</source>
 +
 +
Access an existing browser window:
 +
 +
<source lang="javascript">
 +
var Cc = Components.classes;
 +
var Ci = Components.interfaces;
 +
 +
var windowMediator = Cc["@mozilla.org/appshell/window-mediator;1"].getService(Ci.nsIWindowMediator);
 +
var Firebug = windowMediator.getMostRecentWindow("navigator:browser").Firebug;
 +
var FBL = windowMediator.getMostRecentWindow("navigator:browser").FBL;
 +
</source>
== JavaScript code modules ==
== JavaScript code modules ==
Line 21: Line 123:
</source>
</source>
-
* <code>"resource://firebug/firebug-http-observer.js"<code>: Firebug is using "firebug/http/requestObserver" AMD module.
+
* <code>"resource://firebug/firebug-http-observer.js"</code>: Firebug is using "firebug/http/requestObserver" AMD module.
* <code>"resource://firebug/firebug-trace-service.js"</code>: Firebug is using "firebug/lib/trace" AMD module.
* <code>"resource://firebug/firebug-trace-service.js"</code>: Firebug is using "firebug/lib/trace" AMD module.
Line 44: Line 146:
* <code>"resource://firebug/storageService.js"</code>
* <code>"resource://firebug/storageService.js"</code>
-
== Removed API==
+
== FBL.$ ==
 +
* FBL.$ is deprecate, if you use it you should explicitly provide the document where the element is expected as the second parameter.
 +
 
 +
<source lang="javascript">
 +
var elem = FBL.$("myElem", document);
 +
</source>
 +
 
 +
* See also: http://groups.google.com/group/firebug-working-group/browse_thread/thread/c8081f66a5139312
 +
 
 +
 
 +
== FBL Namespace ==
 +
Firebug is abandoning the idea of using one huge namespace for all APIs - FBL. From this reason all methods and properties of the FBL namespace (implemented in lib.js file) were divided into AMD modules. For example:
 +
 
 +
* string
 +
* dom
 +
* locale
 +
* json
 +
* etc.
 +
 
 +
In order to keep compatibility with existing extensions, the FBL namespace (and global variable) still exists and all APIs are injected int it. As soon as the module directory structure settles down (Firebug 1.9+), using modules in extension will be recommended and using FBL will be marked as obsolete.
 +
 
 +
 
TODO: This is only a rough list of changes, more explanation needed.
TODO: This is only a rough list of changes, more explanation needed.
Line 80: Line 203:
* FBL.mapAsArray -> Firebug.SourceFile.mapAsArray;
* FBL.mapAsArray -> Firebug.SourceFile.mapAsArray;
* FBL.NetFileLink -> Firebug.NetMonitor.NetFileLink
* FBL.NetFileLink -> Firebug.NetMonitor.NetFileLink
-
 
-
== FBL.$ ==
 
-
* FBL.$ is deprecate, if you use it you should explicitly provide the document where the element is expected as the second parameter.
 
-
 
-
<source lang="javascript">
 
-
var elem = FBL.$("myElem", document);
 
-
</source>
 
-
 
-
* See also: http://groups.google.com/group/firebug-working-group/browse_thread/thread/c8081f66a5139312
 
-
 
-
 
-
== FBL in XUL Windows ==
 
-
 
-
* If you using FBL in separate XUL windows/dialogs, make sure you don't include files
 
-
<script type="application/x-javascript" src="chrome://firebug/content/xpcom.js"/>
 
-
<script type="application/x-javascript" src="chrome://firebug/content/lib.js"/>
 
-
 
-
You need to pass FBL and Firebug globals through [https://developer.mozilla.org/en/DOM/window.openDialog window arguments].
 
-
 
-
Or access it from the browser window:
 
-
 
-
<source lang="javascript">
 
-
const windowMediator = Cc["@mozilla.org/appshell/window-mediator;1"].getService(Ci.nsIWindowMediator);
 
-
var FBL = windowMediator.getMostRecentWindow("navigator:browser").FBL;
 
-
</source>
 

Latest revision as of 08:46, 29 July 2011

Firebug 1.8 introduces set of API changes that can impact existing Firebug extensions. This page summarizes these changes and offers solution how to fix broken extensions.

If you have any troubles to convert your extension to be compatible with Firebug 1.8.*, please ask on newsgroups.

Contents

[edit] RequireJS and AMD

Firebug source files are no longer loaded using <script> tags placed in a xul overlay (browserOverlay.xul). Firebug 1.8 uses RequireJS and Asynchronous Module Definition AMD. All files (there are still a few exception) follow the AMD syntax now (see an example).

[edit] Module Directory Structure

Firebug contains implements many AMD modules and these are organized in a directory structure. Every module ID reflects this structure and so it's easier to find appropriate file.

Firebug module directory structure is not finished and so it's not recommended to load existing Firebug modules in Firebug extensions. Existing extension concept (based on overlays) is still supported in Firebug 1.8. Support for module-based extensions will be introduced in Firebug 1.9+

But you can take a quick look how a Firebug panel implementation - using AMD syntax - would look like:

You can also explore entire HelloWorld extension designed for Firebug 1.8.

define([
    "firebug/lib/object",
    "firebug/lib/trace",
],
function(Obj, FBTrace) {
 
function MyPanel() {}
MyPanel.prototype = Obj.extend(Firebug.Panel,
{
    name: "helloworld",
    title: "Hello World!",
});
 
Firebug.registerPanel(MyPanel);
return MyPanel;
});


  • The example uses two AMD modules coming from Firebug "firebug/lib/object" and "firebug/lib/object".
  • The ID (path) of these modules can yet change. Firebug extensions can already use it, but be ready to adapt to new IDs.
  • The structure will be finalized in Firebug 1.9+

You can follow the module structure here.

[edit] Globals

  • FirebugChrome doesn't exist anymore, you need to use Firebug.chrome
  • FBTrace still exists
  • Firebug still exists
  • FBL still exists
  • Domplate still exists

Future versions of Firebug will push on loading appropriate modules instead of using globals. The only existing global variable should be Firebug.

Firebug source and Firebug Extension source (at least those which overlays chrome://firebug/content/firebugOverlay.xul) is now executed within a chrome://firebug/content/firebugFrame.xul scope. So, global variables like gBrowser shouldn't be used (they don't exist in the new scope).

  • gBrowser -> FBL.getTabBrowser();

[edit] XUL windows

This section applies to extensions that creates new XUL windows/dialogs and use Firebug API in them.

Vast majority of Firebug extensions overlays firebugOverlay.xul so, the typical entry in the chrome.manifest (this is still the recommended way) file is following:

overlay chrome://firebug/content/firebugOverlay.xul         chrome://myext/content/myext.xul

These extension should have no problem to work with Firebug 1.8 since they are all running in browser.xul scope where all globals are defined by Firebug.

However, those extension that create new XUL windows or dialogs and use any Firebug global variables could face troubles, especially in cases where any of the following files (and others) are included.

<script type="application/x-javascript" src="chrome://firebug/content/trace.js"/>
<script type="application/x-javascript" src="chrome://firebug/content/xpcom.js"/>
<script type="application/x-javascript" src="chrome://firebug/content/chrome.js"/>
<script type="application/x-javascript" src="chrome://firebug/content/lib.js"/>
<script type="application/x-javascript" src="chrome://firebug/content/domplate.js"/>
<script type="application/x-javascript" src="chrome://firebug/content/firebug.js"/>

These files use AMD syntax and so, they must be loaded by a loader now. In order to use Firebug globals within another XUL scope you have two options:

  • Pass these globals from the browser window (browser.xul) to the XUL window/dialog through window arguments. This is the preferred way.
  • Get an existing browser window and access Firebug in it.

Window arguments:

var params = {
  Firebug: Firebug,
  FBL: FBL
};
 
// This is how you open a dialog and pass parameters to it.
var parent = context.chrome.window;
parent.openDialog("chrome://myext/content/myextwindow.xul",
  "_blank", "chrome,centerscreen,resizable=yes,modal=yes",
  params);
 
// This is how you can get the parameters in onload of the XUL window
var params = window.arguments[0];
var Firebug = params.Firebug;
var FBL = params.FBL;

Access an existing browser window:

var Cc = Components.classes;
var Ci = Components.interfaces;
 
var windowMediator = Cc["@mozilla.org/appshell/window-mediator;1"].getService(Ci.nsIWindowMediator);
var Firebug = windowMediator.getMostRecentWindow("navigator:browser").Firebug;
var FBL = windowMediator.getMostRecentWindow("navigator:browser").FBL;

[edit] JavaScript code modules

This section applies only to extension that explicitly import any of existing Firebug JS code modules.

Some JavaScript code modules has been transformed into AMD modules, but for now extension can still use the Components.utils.import to import them.

An example:

    Components.utils.import("resource://firebug/firebug-http-observer.js", scope);
  • "resource://firebug/firebug-http-observer.js": Firebug is using "firebug/http/requestObserver" AMD module.
  • "resource://firebug/firebug-trace-service.js": Firebug is using "firebug/lib/trace" AMD module.

The new way how to import these modules looks like as follows:

define([
    "firebug/http/requestObserver"
]
function (HttpRequestObserver)
{
    // TODO: module implementation
}

The other modules will be transformed into AMD too.

  • "resource://firebug/debuggerHalter.js"
  • "resource://firebug/firebug-annotation.js"
  • "resource://firebug/firebug-service.js"
  • "resource://firebug/observer-service.js"
  • "resource://firebug/storageService.js"

[edit] FBL.$

  • FBL.$ is deprecate, if you use it you should explicitly provide the document where the element is expected as the second parameter.
var elem = FBL.$("myElem", document);


[edit] FBL Namespace

Firebug is abandoning the idea of using one huge namespace for all APIs - FBL. From this reason all methods and properties of the FBL namespace (implemented in lib.js file) were divided into AMD modules. For example:

  • string
  • dom
  • locale
  • json
  • etc.

In order to keep compatibility with existing extensions, the FBL namespace (and global variable) still exists and all APIs are injected int it. As soon as the module directory structure settles down (Firebug 1.9+), using modules in extension will be recommended and using FBL will be marked as obsolete.


TODO: This is only a rough list of changes, more explanation needed.

  • FBL.CCIN, FBL.CCSV and FBL.QI are obsolete, use "firebug/lib/xpcom"
  • HTMLLib is not part of Firebug namespace, you need to include "firebug/lib/htmlLib"
  • $STR, $STRP, $STRP, registerStringBundle, getStringBundle, getDefaultStringBundle, getPluralRule, internationalize and internationalizeElements are part of "firebug/lib/locale"
  • dispatch and dispatch2 are part of "firebug/lib/events" module
  • All preferences should be accessed through "firebug/lib/options" module
  • FBL.deprecated is now Deprecated.deprecated (firebug/lib/deprecated)
  • FBTrace comes from "firebug/lib/trace"
  • New modules: url, wrapper (don't use the API from FBL)
  • FBL.findNext and FBL.findPrevious no longer exist.
  • FirebugChrome namespace: getBrowsers, getCurrentBrowsers, getCurrentURI API removed and part of firefox/firefox module
  • There is a new <div> fbMainFrame (wrapping fbContentBox)
  • Firebug.getTabForWindow and getTabIdForWindow is removed, use firefox/window module (getWindowProxyIdForWindow).
  • FBL.openWindow, FBL.viewSource, FBL.getBrowserForWindow are part of firefox/firefox
  • FBL.ToggleBranch is now ToggleBranch.ToggleBranch
  • FBL.Continued removed.
  • FBL.isAncestorIgnored removed
  • FBL.ErrorMessage -> FirebugReps.ErrorMessageObj
  • FBL.fatalError removed
  • FBL.ErrorCopy -> FirebugReps.ErrorCopy
  • FBL.EventCopy -> DOM.EventCopy
  • FBL.Property -> FirebugReps.PropertyObj
  • FBL.findScripts -> Firebug.SourceFile.findScripts;
  • FBL.findScriptForFunctionInContext -> Firebug.SourceFile.findScriptForFunctionInContext;
  • FBL.findSourceForFunction -> Firebug.SourceFile.findSourceForFunction;
  • FBL.getSourceLinkForScript -> Firebug.SourceFile.getSourceLinkForScript;
  • FBL.getSourceFileByHref -> Firebug.SourceFile.getSourceFileByHref;
  • FBL.sourceURLsAsArray -> Firebug.SourceFile.sourceURLsAsArray;
  • FBL.sourceFilesAsArray -> Firebug.SourceFile.sourceFilesAsArray;
  • FBL.mapAsArray -> Firebug.SourceFile.mapAsArray;
  • FBL.NetFileLink -> Firebug.NetMonitor.NetFileLink
Personal tools