Labs/Jetpack/Reboot/JEP/103
From MozillaWiki
Contents
JEP 103 - Panel
- Type: API
- Status: Accepted/Pre-Production
- Champion: Myk Melez <myk@mozilla.org>
- Bug: bug 494238
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:
Use Cases
- 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.
- 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
- 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
- How does the extension get notified when the panel has been shown and the document property is available? Perhaps the
showmethod could accept acallbackparameter that gets called? - 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)?
- How does content in the panel communicate with the extension?
- 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)?
