Revision Content

{{ warning("The DevTools API is not available yet. The DevTools API is still WIP. If you notice any inconsistency, please let Paul know.") }}

Introduction

The DevTools API provides a way to register and access developer tools in Firefox.

In term of User Interface, each registered tool lives in its own tab (we call one tab a panel). These tabs are located in a box we call a Toolbox. A toolbox can be hosted in a browser tab (at the bottom or on the side), or in its own window (we say that the toolbox is undocked). A Toolbox (and all the tools it contains) is linked to a Target, which the object the tools are debugging. A target is usually a web page (a tab), but can be other things (a chrome window, a remote tab,…).

In term of code, each tool has to provide a ToolDefinition object. A definition is a JS light object that exposes different informations about the tool (like its name and its icon), and a build method that will be used later-on to start an instance of this tool. The gDevTools global object provides methods to register a tool definition and to access tool instances. An instance of a tool is called a ToolPanel. The ToolPanel is built only when the tool is selected (not when the toolbox is opened). There is no way to "close/destroy" a ToolPanel. The only way to close a toolbox is to close its containing toolbox. All these objects implement the EventEmitter interface.

API

gDevTools

Method

Description

void registerTool(toolDefinition)

Register a new tool, and build a new panel in each exisiting toolbox.

void unregisterTool(toolId)

Unregister a tool. Destroy any open panel.

Map(toolId,toolDefinition) getToolDefinitions()

Get a copy of the internal toolID:toolDefinition Map.

Toolbox openToolbox(target, host=null, toolId=null)

Open a toolbox for the specified target. If host is unspecified, Toolbox will decide where to open the toolbox (below the tab, on the side or in its own window). If tooldId is unspecified, Toolbox will decide which to open by default.

void closeToolbox(target)

Close a toolbox.

Toolbox openToolboxForTab(tab, toolId=null)

Open a toolbox for a specified tab. A tab target is built internally.

void toggleToolboxForTab(tab, toolId=null)

Toggle the toolbox for a specified tab.

Map(Target,Toolbox) getToolboxes()

Get a copy of the internal target:toolbox Map.

Toolbox getToolboxForTarget(target)

Retrieve the toolbox for a specified target.

ToolPanel getPanelForTarget(tooldId, target)

Retrieve the instance of a tool for a specified target.

Events

Description

tool-registered

a tool has been registered. [toolId]

tool-unregistered

a tool has been unregistered. [toolId]

toolbox-ready

a toolbox has been opened.[Toolbox]

toolbox-destroyed

a toolbox has been closed. [xul:tab]

{tooldId}-ready

a tool has been activated. [Toolbox, ToolPanel]

Toolbox

Method

Description

Map(toolId, toolPanel) getToolPanels()

Get a copy of the internal toolId:panel Map.

Target target

HostType hostType

Where the toolbox lives.

toolId currentToolId

The toolId of the selected tool.

void selectTool(toolId)

Select a tool.

Node getNotificationBox()

Retrieve the surrounding notificationbox (useful to show notify the user even if a tool is not visible).

void destroy()

Close the toolbox.

Events

Description

ready

the toolbox is ready to use.

{toolId}-ready

a tool is ready to use.

host-changed

the location of the toolbox changed.

destroyed

The toolbox has been closed

select{{notimplemented_inline()}}

A tool has been selected. [toolId]

ToolDefinition

Method

Description

String id

A unique id. Must not contained white spaces (it will be used as an id).

String icon

The url of the icon.

String label

Tool's name. Showed in Firefox' tool menu and in the Toolbox' tab.

String key

Main keybinding key.

Number ordinal

The position of the tool's tab within the toolbox (default is 99).

String modifiers

Main keybinding modifiers.

String accesskey

Menu accesskey.

Boolean isTargetSupported(Target)

If the target is not supported, the toolbox will hide the tab.

String url

A tool lives in its own iframe. Toolbox will load this URL.

ToolPanel build(iframeWindow, Toolbox)

This function is called when the user select the tool tab. It is called only once ToolDefinition.url is loaded.

TargetType

FIXME:

HostType

FIXME

ToolPanel

Method

Description

Target target

FIXME

Target destroy()

FIXME

Events

Description

ready

FIXME

EventEmitter

Method

Description

on(eventName, listener)

FIXME

off(eventName, listener)

FIXME

once(eventName, listener)

FIXME

emit(eventName, ...extraArgs)

FIXME

listener function(eventName, ...extraArgs) {}

FIXME

ToolSidebar {{notimplemented_inline()}}

To build a sidebar in your tool, first, add a xul:tabbox where you want the sidebar to live:

A sidebar is composed of tabs. Each tab will hold an iframe. For example, in the Inspector, there are 3 views (Computed View, Rule View, Layout View). The user can select the tab he wants to use.

If the availability of the tabs depends on some tool-related conditions, we might not want to let the user select tabs. This API provides methods to hide the tabstipe. For example, in the Web Console, there are 2 views (Network View and Object View). These views are only available in certain conditions controlled by the WebConsole code. So it's up the WebConsole the hide and show the sidebar, and select the correct tab.

If the loaded document exposes a window.setPanel(ToolPanel) function, the sidebar will call it once the document is loaded.