Labs/Jetpack/Reboot/JEP/102

JEP 102 - Single UI Element

• Champion: Aza Raskin - aza@mozilla.com
  • Other Peeps: Alex Faaborg, Daniel Buchner, Jennifer Boriss, Dietrich Ayala
• Status: Under Review
• Bug Tickets:
  • bug 543585 - Phase 1: Core API in place, simple status-bar-like UI
  • bug 568932 - Phase 2: Work with Firefox UX to complete the UI
• Type: API

Proposal

/**
Creates a new simple feature, whose properties are that it has a small 16x16
pixel display, as well as a larger display that defaults to 350px by 450px.
@constructor
@param options {object}
  @prop content {uri|html}
        This is the small view of the feature.
        uri: A link to the URL of either an icon or a webpage.
        html: An HTML string that will be rendered.
  @prop [panel] {uri|html|panel}
        See above descriptions for URI and HTML content.
        panel: A reference to a panel object ([[Labs/Jetpack/Reboot/JEP/103|JEP 103]]
        If a panel is specified then the default action is that a 
        click on the content area opens the panel. If you wish 
        to override this behavior you do it in the standard way:
        by creating a new widget.onClick that returns false, or
        calls event.preventDefault().
  @prop [on*] {function}
        Event handlers. Potential to be all standard events. But for now: load, click, mouseover, mouseout, DOMContentReady.
**/
widget = require("widget").Widget(options);

Sizing

The bar should have two sizes: one where the height of the widgets are 24px and one where they are 16px. The size is set by the user/Firefox, and cannot be changed via this API. For now, the widgets are always rendered as if at a height of 24px and then scaled to 16px height.

Customization

• Customization of the visible widgets should be handled in the same manner that Firefox toolbar customizations are made.

Not-implemented Yet

• Adding event handlers on the widget object
• Removing event handlers
• Enumerating event handlers
• Panel support
• Setting image/content/panel on the widget object

Open Issues

• What are the conditions that we should impose on add-ons being included in this UI element.
• How is overflow handled?
• Can users pin a widget?
• Can users change widget order? Via drag-and-drop?
• Can widgets stay alive, but manage their own visibility? (ie: only show if there's activity)
• Can widgets change their own position in the display? Or force themselves out of overflow into the visible set?

Dependencies & Requirements

• JEP 103 - Panel
• JEP 115 - ContentFrame
• URL constructor - bug 564624
• Image constructor

Use Cases

• Create a email notifier that shows you a small view that has the latest count/sparkline of emails yet to be read, and when you click on it it shows the detailed information about those unread messages.
• A clock, which has no detail view. Similarly, an x-eyes reimplementation (the eyes follow your cursor around).
• A Stumble Upon-style interface, where the small view allows you to upvote/downvote a page, and when a triangle is clicked shows a detailed view of ratings of this page.
• Snow-globe, where when you click it causes the snow to swirl around the page you are looking at. Clicking a little gear opens a detailed view for setting the color and strength of the snow storm. (Like the previous case.)
• An expanding search interface. It is displayed as a small search box. When you click in it, the search box expands in width with a quick animation. As you start typing, a panel appears which has search results listed in which you can arrow up/down, or mouse to.

Examples

Snow Globe

function SnowGlobe(win){
  // ...
}

var globes = {};

widget = require("basic-widget").Widget({
  image: "snowglobe.png",
  onClick: function(){
    tabs = require("tabs");
    var win = tabs.focused.contentWindow;
    if( !globes[win] ) globes[win] = new SnowGlobe(win);
    globes[win].shake();
  }
});

Mobile Reddit

widget = require("basic-widget").Widget({
  image: "http://reddit.com/favicon",
  panel: "http://m.reddit.com"
})

Wikipedia Lookup

widget = require("basic-widget").Widget({
  image: "http://wikipedia.com/favicon",
  panel: "Loading..."
})

widget.onClick(function(){
  var sel = require("selection").text;
  var url = "http://wikipedia.com/search?q=" + sel;
  widget.panel.content = url;
});