Labs/Jetpack/Reboot/JEP/110: Difference between revisions

Jump to navigation Jump to search

Labs/Jetpack/Reboot/JEP/110 (view source)

Revision as of 23:13, 9 April 2010

849 bytes added ,  9 April 2010
revise and expand spec based on pre-implementation review
(make the set of changes discussed in the forum)
(revise and expand spec based on pre-implementation review)
Line 1: Line 1:
== JEP 110 - Tabs ==
= JEP 110 - Tabs =


* Champion: Aza Raskin - aza@mozilla.com
* Champion: Myk Melez <myk@mozilla.org>
* Status: Info Needed
* Status: Approved
* Bug Ticket:
* Bug Ticket: {{bug|549317}}
* Type: API
* Type: API


= Introduction =


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


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


Import lives in the "tabs" module.
* 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.


<pre class="brush:js">
= Interface =
/**
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.
== <tt>tabs</tt> module ==


/**
The <tt>tabs</tt> module provides the API. It exports one symbol: the <tt>tabs</tt> singleton.
A method called when a tab is shown.
@param event {Event} the event
**/
tabs.onShow(event)


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


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


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


/**
The <tt>tabs</tt> singleton has one property, <tt>activeTab</tt>, which is a <tt>Tab</tt> object that represents the currently active tab.
A method called when a tab's content is loaded.
@param event {Event} the event
**/
tabs.onLoad(event)


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


/**
The <tt>tabs</tt> singleton has one method, <tt>open</tt>, which opens a new tab:
A method called when a tab's content has been painted.
@param event {Event} the event
**/
tabs.onMozAfterPaint(event)


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


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


// Get one of the tab objects
The <tt>tabs</tt> singleton has a number of event callback properties with which consumers can register callback functions via the standard mechanisms as described in the [[Labs/Jetpack/Design_Guidelines|design guidelines]]:
var tab = tab[0];


/**
; onActivate: a tab is activated, whether programmatically or by user action (clicking on the tab, switching windows, etc.)
A method called when the tab is shown.
; onDeactivate: a tab is deactivated
@param event {Event} the event
; onOpen: a tab is opened
**/
; onClose: a tab is closed
tab.onShow(event)
; onDOMReady: the text content of a top-level document in a tab has been loaded and parsed into a DOMDocument object (i.e. the <tt>DOMContentLoaded</tt> 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 <tt>load</tt> event has occurred)
; onPaint: the visual representation of a top-level document in a tab has changed (i.e. the <tt>MozAfterPaint</tt> event has occurred)


/**
When a callback function is called, its first parameter is an <tt>Event</tt> object representing the event that occurred, and its second parameter is a <tt>Tab</tt> object representing the tab on which it occurred, i.e.:
A method called when the tab is hidden.
@param event {Event} the event
**/
tab.onHide(event)


/**
  tabs.onActivate = function(event, tab) { ... };
  A method called when the tab is closed.
@param event {Event} the event
**/
tab.onClose(event)


/**
When the <tt>tabs</tt> singleton is iterated via <tt>[https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Statements/for_each...in for each...in]</tt>, it yields a sequence of <tt>Tab</tt> objects representing the tabs in all application windows:
A method called when the tab's content is loaded.
@param event {Event} the event
**/
tab.onLoad(event)


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


/**
The order by which tabs are returned in the iteration is not specified, may change in the future, and should not be counted upon.
A method called when the tab's content has been painted.
@param event {Event} the event
**/
tab.onPaint(event)


/**
== <tt>Tab</tt> objects ==
Make this the active tab.
**/
tab.activate()


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


/**
<tt>Tab</tt> objects have the following properties:
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.
  * The properties for the tabs.
@param index {Number} the new location in the tab set
  * @prop title {String}
@param window {Window}  
  *      the title of the page currently loaded in the tab
        the new window; optional if moving to a new location
  * @prop location {URL}
        within the existing window
  *      the URL of the page currently loaded in the tab
**/
  * @prop contentWindow {DOMWindow}
tab.move(index, window)
  *      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 ===
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


</pre>
<tt>Tab</tt> objects have the following methods:


=== Difficulty ===
/**
  * 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)


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


=== Key Issues ===
<tt>Tab</tt> objects have the same event callback properties as the <tt>tabs</tt> singleton, except that they don't have the <tt>onOpen</tt> callback.


= Implementation Phases =


=== Dependencies & Requirements ===
== Phase One ==
* 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?


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


=== Internal Methods ===
* <tt>tabs</tt> singleton
* What methods, mechanisms, or resources does this provide internally within the Jetpack platform code.
** properties:
 
*** activeTab
 
** methods:
=== API Methods ===
*** open
* What are the pretty API wrapped methods externally exposed to Jetpack developers?
** callbacks:
 
*** onActivate
 
*** onDeactivate
=== Use Cases ===
*** onOpen
 
*** onClose
* Move a tab to be the first tab, or re-order tabs based on semantic grouping
*** onLoad
* Close a set of tabs
* <tt>Tab</tt> objects
* Open a new tab to a contextually aware location
** properties
* Change the background color of the currently active tab
*** title
* Change the color of the background of a tab-handle
*** location
* Show the Delicious tab-o-meter of the current tab
*** contentWindow
*** contentDocument
** methods
*** activate
*** load
*** close
** callbacks
*** onActivate
*** onDeactivate
*** onClose
*** onLoad
MykMelez
canmove, Confirmed users
2,056

edits

Retrieved from "https://wiki.allizom.org/Special:MobileDiff/214801"

Navigation menu