Labs/Jetpack/Reboot/JEP/110

JEP 110 - Tabs

• Champion: Aza Raskin - aza@mozilla.com
• Status: Info Needed
• Bug Ticket:
• Type: API

Proposal

Tabs are a fundamental unit of the browser (for now). We need reasonable ways of interacting with them.

Import lives in the "tabs" module.

/**
tabs is an immutable array of Tab objects
**/
tabs = require("tabs").tabs;

When the following methods are called, the "this" of the method is the tab in question.

/**
 A method called when a tab is shown.
 @param event {Event} the event
**/
tabs.onShow(event)

/**
 A method called when a tab is hidden.
 @param event {Event} the event
**/
tabs.onHide(event)

/**
 A method called when a tab is opened.
 @param event {Event} the event
**/
tabs.onOpen(event)

/**
 A method called when a tab is closed.
 @param event {Event} the event
**/
tabs.onClose(event)

/**
 A method called when a tab's content is loaded.
 @param event {Event} the event
**/
tabs.onLoad(event)

/**
 A method called when a tab's content is ready.
 @param event {Event} the event
**/
tabs.onDOMReady(event)

/**
 A method called when a tab's content has been painted.
 @param event {Event} the event
**/
tabs.onMozAfterPaint(event)

/**
 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 recent application window
**/
tabs.open(url, window)

/**
 The properties of the tab.
 @prop activeTab {Tab}
       The currently active tab
**/
tabs.property

// Get one of the tab objects
var tab = tab[0];

/**
 A method called when the tab is shown.
 @param event {Event} the event
**/
tab.onShow(event)

/**
 A method called when the tab is hidden.
 @param event {Event} the event
**/
tab.onHide(event)

/**
 A method called when the tab is closed.
 @param event {Event} the event
**/
tab.onClose(event)

/**
 A method called when the tab's content is loaded.
 @param event {Event} the event
**/
tab.onLoad(event)

/**
 A method called when the tab's content is ready.
 @param event {Event} the event
**/
tab.onDOMReady(event)

/**
 A method called when the tab's content has been painted.
 @param event {Event} the event
**/
tab.onPaint(event)

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

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

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

/**
 Move the tab to a new location in the tab set.
 @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)

/**
 The properties for the tabs.
 @prop style {cssStyleString}
       The css style string for the tab.
 @prop index {integer}
       The index the tab is displayed at in its parent window
 @prop location {url} URL of the tab
 @prop title {string} The title of the page
 @prop favicon {url} URL of the displayed favicon
 @prop contentDocument {document}
 @prop contentWindow {window}
 @prop [ownerWindow] {jetpack window} The window the tab belongs to
 @prop [thumbnail] {canvas} A thumbnail of the currently displayed page
 @prop onShow {Function} event handler to call when a tab is activated
 @prop onHide {Function} event handler to call when a tab is deactivated
**/
tab.property

Difficulty

This is a medium difficulty to implement, but made easier by a pre-existing implementation.

Dependencies & Requirements

• Are there any Firefox platform bugs blocking it?
• Does other Jetpack platform code need to be modified or added?
• Does its implementation affect any other projects or code?

Internal Methods

• What methods, mechanisms, or resources does this provide internally within the Jetpack platform code.

API Methods

• What are the pretty API wrapped methods externally exposed to Jetpack developers?

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