Your Search Results

    DevTools API

    Warning: The DevTools API is not available yet. The DevTools API is still WIP. If you notice any inconsistency, please let The Firefox Developer Tools Team know.

    While this api is currently work-in-progress, there are usable portions of page inspector and debugger that may be used currently.

     

    Introduction

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

    In terms 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 within 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 is 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 terms of code, each tool has to provide a ToolDefinition object. A definition is a JS light object that exposes different information 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 toolPanel 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 A new tool has been selected [toolId]
    {toolId}-selected Tool {toolId} has been selected

    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 inMenu Whether to list the tool in the Web Developer menu.
    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

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

        <splitter class="devtools-side-splitter"/>
        <tabbox id="mytool-sidebar" class="devtools-sidebar-tabs" hidden="true">
          <tabs/>
          <tabpanels flex="1"/>
        </tabbox>
     
    A sidebar is composed of tabs. Each tab will hold an iframe. For example, in the Inspector, there are 3 tabs (Computed View, Rule View, Layout View). The user can select the tab he wants to see.
     
    If the availability of the tabs depends on some tool-related conditions, we might want to not let the user select a tab. This API provides methods to hide the tabstripe. 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.
     
    Method Description
    new ToolSidebar(xul:tabbox, ToolPanel, uid, showTabstripe=true) ToolSidebar constructor
    void addTab(tabId, url, selected=false) Add a tab in the sidebar
    void select(tabId) Select a tab
    void hide() Hide the sidebar
    void show() Show the sidebar
    void toggle() Toggle the sidebar
    void getWindowForTab(tabId) Get the iframe containing the tab content
    tabId getCurrentTabID() Return the id of tabId of the current tab
    tabbox getTab(tabId) Return a tab given its id
    destroy() Destroy the ToolSidebar object
    Events Description
    new-tab-registered A new tab has been added
    {tabId}-ready Tab is loaded and can be used
    {tabId}-selected Tab has been selected and is visible
    {tabId}-unselected Tab has been unselected and is not visible

    Examples

    Register a tool

    gDevTools.registerTool({
      // FIXME: missing key related properties.
      id: "inspector",
      icon: "chrome://browser/skin/devtools/inspector-icon.png",
      url: "chrome://browser/content/devtools/inspector/inspector.xul",
      get label() {
        let strings = Services.strings.createBundle("chrome://browser/locale/devtools/inspector.properties");
        return strings.GetStringFromName("inspector.label");
      },
    
      isTargetSupported: function(target) {
        return !target.isRemote;
      },
    
      build: function(iframeWindow, toolbox, node) {
        return new InspectorPanel(iframeWindow, toolbox, node);
      }
    });
    

    Open a tool, or select it if the toolbox is already open:

    let target = TargetFactory.forTab(gBrowser.selectedTab);
    let toolbox = gDevTools.openToolbox(target, null, "inspector");
    
    toolbox.once("inspector-ready", function(event, panel) {
      let inspector = toolbox.getToolPanels().get("inspector");
      inspector.selection.setNode(target, "browser-context-menu");
    });
    

    Add a sidebar to an existing tool:

    let sidebar = new ToolSidebar(xulTabbox, toolPanel, "toolId");
    sidebar.addTab("tab1", "chrome://browser/content/.../tab1.xhtml", true);
    sidebar.addTab("tab2", "chrome://browser/content/.../tab2.xhtml", false);
    sidebar.show();
    

    Document Tags and Contributors

    Tags:
    Last updated by: CompleteAbstraction,