Labs/Jetpack/Reboot/JEP/110

JEP 110 - Tabs

• Champion: Aza Raskin - aza@mozilla.com
• Status: Accepted/In-Queue
• 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");

/**
 These are global callbacks that come into affect when
 any of these happen to any tab.
 @param eventName {string}
        Is one of focus, blur, close, open, load, domready, mozafterpaint,
        move
 @param callback {function}
        The function gets passed an "event" object and the the "this" of
        that function is the tab in question.
**/
tabs.bind( eventName, callback );

/**
 Unbinds the event handler
 Without any arguments, all bound events are removed. You can also unbind 
 custom events registered with bind. If the type is provided, all bound 
 events of that type are removed. If the function that was passed to bind is
 provided as the second argument, only that specific event handler is 
 removed.
 @param [eventName] {string}
 @param [func] {function}
**/
tabs.bind( eventName, func );

/**
 This causes an event to occur or a message to be sent to all tabs.
 @param eventName {string}
        The event to trigger. For now this is only "open"
 @param data {string|object}
        In the case of open this is the URL, if this is a dictionary
        then otherData won't be needed.
 @param [otherData] {object}
        Other data to be passed to the event handler.
**/
tabs.trigger( eventName, data, otherData )

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

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

/**
 Same as for tabs, but effects the particular tab in question.
**/
tab.bind( eventName, callback )

/**
 Same as for tabs, but effects the particular tab in question.
**/
tab.unbind( eventName, callback )

/**
 Mostly the same as for the tabs case, the only difference being:
 @param eventName {string}
        Is one of focus, close, load, move
**/
tab.trigger( eventName, data, otherData )

/**
 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 [window] {jetpack window} The window the tab belongs to
 @prop [thumbnail] {canvas} A thumbnail of the currently displayed page    
**/
tab.property

Sugar Functions

// Sugar for tabs.on functionality
tabs.onFocus( function )
tabs.onBlur( function )
tabs.onClose( function )
tabs.onOpen( function )
tabs.onLoad( function )
tabs.onDomReady( function )
...
// and the same for each Tab instance.

// Sugar for tabs.trigger functionality
tabs.open( url, options )
...
// And the same for each Tab instance, plus
tab.move( index, options )
// index = absolute index, "+3"/"-1" for relative
// options for moving to other windows

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?