Labs/Jetpack/Reboot/JEP/102

JEP 102 - Single UI Element

• Champion: Aza Raskin - aza@mozilla.com
  • Other Peeps: Alex Faaborg
• Status: Under Review
• Bug Ticket:
• Type: API

Proposal

/**
Creates a new simple feature, whose properties are that it has a small 32x32
pixel display, as well as a larger display (that defaults to some size).
@constructor
@param options {object}
  @prop smallView {uri|html|xml}
        This is the small view of the feature.
        uri: A link to the URL of either an icon, or a webpage
        html: A html string that will be shown in the small view
        xml: E4X version of the above
  @prop [detailView] {uri|html|xml}
        See above descriptions.
  @prop [alwaysDisplayed=true] {bool}
        Used for things that only appear under certain conditions
**/
feature = new require("simple-feature").Feature(options);

/**
Event handlers
@method
@param eventName {string}
       All of the standard events: click, mouseover, mouseout, mousedown, 
       mouseup, keydown, keyup
@param callback {function}
**/
feature.bind( eventName, callback )

/**
Remove event handlers. 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.
@method
@param eventName {string}
@param callback {function}
**/
feature.unbind( eventName, callback )

/**
@prop [smallView] {canvas|window}
      If there was a image passed into the constructor this will bea canvas
      you can draw on. It updates the displayed icon in real time. If there
      was a page, then this is a window element.
@prop [detailView] {window}
      A pointer to the detailed view. Changing the width/height of this window
      changes the detail view's total width and height.
**/
feature.property

• How hard is it to implement? Hard.

Notes

• Do we really need all of those events?
• onClick automatically opens the detail page. (Then how to override that)
• Dependence: ContentFrame, Panel
• feature.remove()

Key Issues

• What are the conditions that we should impose on add-ons being included in this UI element.
• The code new require("simple-feature").Feature(options) is actually wrong due to the way the new operator works, which would, this code, regard require as a constructor. The correct code would be new (require("simple-feature")).Feature(options).

Dependencies & Requirements

• JEP 103 - Panel
• Update-allowable implementation of "icon" - may share similar implementation of content area with Panel and other JEPs

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

• 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, or an x-eyes reimplementation.
• 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.)