Labs/Jetpack/Reboot/JEP/110

JEP 110 - Tabs

• Champion: Myk Melez <myk@mozilla.org>
• Status: Approved
• Bug Ticket: bug 549317
• Type: API

Introduction

Tabs are a fundamental element of the browser. Add-ons should have access to them.

Use Cases

• move a tab to be the first tab, or re-order tabs based on semantic grouping;
• close a set of tabs;
• open a new tab to a contextually aware location;
• change the background color of the currently active tab;
• change the color of the background of a tab-handle;
• show the Delicious tab-o-meter of the current tab.

Interface

tabs module

The tabs module provides the API. It exports one symbol: the tabs singleton.

let tabs = require("tabs").tabs;

tabs singleton

Properties

The tabs singleton has one property, activeTab, which is a Tab object that represents the currently active tab.

Methods

The tabs singleton has one method, open, which opens a new tab:

/**
 * Open a new tab.
 * @param url {URL} the URL to load in the tab; optional;
 *        if not provided, about:blank will be loaded in the tab
 * @param window {Window} the window in which to open the tab;
 *        optional; if not provided, the tab will be opened 
 *        in the most recently active application window
 **/
tabs.open(url, window)

Callbacks

The tabs singleton has a number of event callback properties with which consumers can register callback functions via the standard mechanisms as described in the design guidelines:

onActivate

a tab is activated, whether programmatically or by user action (clicking on the tab, switching windows, etc.)

onDeactivate

a tab is deactivated

onOpen

a tab is opened

onClose

a tab is closed

onReady

the text content of a top-level document in a tab has been loaded and parsed into a DOMDocument object (i.e. the DOMContentLoaded event has occurred)

onLoad

the text, image, style, and script content of a top-level document in a tab has been loaded (i.e. the DOM load event has occurred)

onPaint

the visual representation of a top-level document in a tab has changed (i.e. the MozAfterPaint event has occurred)

When a callback function is called, its first parameter is an Event object representing the event that occurred, and its second parameter is a Tab object representing the tab on which it occurred, i.e.:

tabs.onActivate = function(event, tab) { ... };

When the tabs singleton is iterated via for each...in, it yields a sequence of Tab objects representing the tabs in all application windows:

for each (let tab in tabs) { ... }

The order by which tabs are returned in the iteration is not specified, may change in the future, and should not be counted upon.

Tab objects

Properties

Tab objects have the following properties:

/**
 * The properties for the tabs.
 * @prop title {String}
 *       the title of the page currently loaded in the tab
 * @prop location {URL}
 *       the URL of the page currently loaded in the tab
 * @prop contentWindow {DOMWindow}
 *       the window object for the page currently loaded in the tab
 * @prop contentDocument {DOMDocument}
 *       the document object for the page currently loaded in the tab
 * @prop favicon {URL}
 *       the URL of the favicon for the page currently loaded in the tab
 * @prop style {String}
 *       the CSS style for the tab
 * @prop index {Number}
 *       the index of the tab relative to other tabs in the application window
 * @prop window {Window}
 *       the window to which the tab belongs
 * @prop thumbnail {Canvas}
 *       a thumbnail of the page currently loaded in the tab
**/
tab.property

Methods

Tab objects have the following methods:

/**
 * Make this the active tab.
 **/
tab.activate()

/**
 * Load a URL in the tab.
 * @param url {URL} the URL to load in the tab
 **/
tab.load(url)

/**
 * Close the tab.
 **/
tab.close()

/**
 * Move the tab within the window-specific set of tabs to which it belongs.
 * @param index {Number}
 *        the new location in the tab set
 * @param window {Window}
 *        the new window; optional if moving to a new location
 *        within the existing window
 **/
tab.move(index, window)

Callbacks

Tab objects have the same event callback properties as the tabs singleton, except that they don't have the onOpen callback.

Implementation Phases

Phase One

In the first phase of development, the following elements of the API should be implemented:

• tabs singleton
  • properties:
    • activeTab
  • methods:
    • open
  • callbacks:
    • onActivate
    • onDeactivate
    • onOpen
    • onClose
    • onLoad
• Tab objects
  • properties
    • title
    • location
    • contentWindow
    • contentDocument
  • methods
    • activate
    • load
    • close
  • callbacks
    • onActivate
    • onDeactivate
    • onClose
    • onLoad