Labs/Jetpack/Reboot/JEP/103

From MozillaWiki
< Labs‎ | Jetpack‎ | Reboot‎ | JEP
Jump to: navigation, search

JEP 103 - Panel

Introduction

Jetpack should have an API that enables extensions to create rich content panels that float above the browser window. An example of this kind of functionality is shown in the popular add-on TwitterFox:

20090821-rbhrm8ddj2xk6f88uy66gdf97h.jpg

Use Cases

  1. The primary use case for a panel is to temporarily provide more detailed information about a subject about which an extension permanently displays a summary.
    • For example, an extension like TwitterFox in the image above, which provides information about users' Twitter accounts, might show a user the number of unviewed tweets in a status bar element and the tweets themselves in a panel when the user clicks on the element.
    • And an extension that provides information about the weather might show a brief summary of weather conditions in a toolbar button and an extended forecast in a panel when the user presses the button.
  2. Interactive Content Annotations
    • This would be a tooltip-like element that would overlay extended content when prompted by an action(s) performed in the content space
  3. Settings View
    • Panels could be used to display settings UI when settings functionality is made available in a later release

Implementation

Module

The API is implemented by the panel Cuddlefish module. The module exports the following properties:

Panel
a constructor for Panel objects

Panel

The Panel object represents a panel. Panel objects are configurable by setting their properties directly or passing a property collection as the options parameter of their constructor.

Constructor

The Panel constructor has the following parameters:

options
a property collection that configures the object

Properties

anchor
DOMElement; a DOM element to which to visually attach the panel; if not set, the panel will be horizontally and vertically centered above the browser window
content
String; the URL to load in the panel, or a string of HTML to display in it
width
String (default: "400px"); the width of the panel as a CSS numeric value
height
String (default: "300px"); the height of the panel as a CSS numeric value

Methods

show
show the panel to the user. Extensions should only call this method as the result of user action (f.e. when a user clicks on a UI element associated with an extension). Returns the panel.
hide
hide the panel from the user. Jetpack will hide a panel automatically when the user clicks outside the panel, so extensions shouldn't generally provide UI within the panel for closing it. Reserve the use of this method for special cases that don't fit the typical panel interaction model (f.e. the Remove Bookmark button in the Edit This Bookmark panel that appears when a user clicks the star icon for a bookmarked page in the Firefox user interface). Returns the panel.

Examples

Open a panel that displays some HTML:

const Panel = require("panel").Panel;
let panel = new Panel(
  content: "Look ma, a panel!"
).show();

Open a panel that displays a website:

const Panel = require("panel").Panel;
let panel = new Panel(
  content: "http://example.com/"
).show();

Issues

  1. How does the extension get notified when the panel has been shown and the document property is available? Perhaps the show method could accept a callback parameter that gets called?
  2. Should we enforce the recommendation that panels only be opened as the result of user action (f.e. clicking on a UI element associated with the extension) and not as the result of some background event like a network update (which should be handled by a notification), and how could we enforce that (f.e. a method similar to the one that Gecko uses to suppress non-user-initiated popup windows)?
  3. How does content in the panel communicate with the extension?
  4. Should we treat the content loaded into the panel as untrusted and provide barriers to its ability to access the extension's JavaScript context (f.e. by disabling JavaScript within the panel's content iframe)?

References