Labs/Jetpack/JEP/23

	THIS PAGE IS A WORKING DRAFT
	The page may be difficult to navigate, and some information on its subject might be incomplete and/or evolving rapidly. If you have any questions or ideas, please add them as a new topic on the discussion page.

CONSIDER THE FOLLOWING: We could augment our implementation of this UI mechanism by including aspects of Clientcide's PointyTips. I believe it may help us cover a broader set of use-cases.

DISCUSSION: Should we pursue an implementation that closely mirrors this existing venture into similar territory? -

JEP 23 - Panels

• Champion: Aza Raskin <aza at mozilla dot com>
• Status: Implementing
• Type: API Track
• Created: 21 Aug 2009
• Reference Implementation: None
• Relevant Bugs:
• JEP Index

Introduction and Rationale

This JEP describes the API for creating style-able rich content panels (windows) that float above the browser window.

An example of this kind of functionality is shown in the popular add-on, TwitterFox:

Proposal

Panel access will live at jetpack.panel.

Panel overview

Most of the action occurs in jetpack.panel.open(...), which returns a Panel object, which can then be manipulated.

Opening a Panel

CONSIDER: Here are some additional and alternate options from an existing implementation that is quite mature: StickyWin Documentation

myPanel = jetpack.panel.open(...);

Optional Arguments

• url/html: You can have one of either a url or an html parameter. The url (either absolute or relative) is what the content of the panel shows. Html, on the other hand, is the manually created html to be displayed. Works just like the slidebar.
• style: Is either an inline CSS style for the panel (transparency, rounded corners, color, etc.), or a url that points to a CSS file.
• width/height: Defaults to 320x240 pixels.
• transient: A bool that defaults to true. A transient panel is one that disappears when you click outside the panel, a key press goes someplace that isn't the panel, or the escape key is pressed. A non-transient panel must be dismissed explicitly.
• restoreFocus: A bool that defaults to true. When the panel is closed, if true, then Jetpack refocuses last element that had focus in the browser. If false, nothing will be in focus.
• takeFocus: A bool that defaults to true. If this is true, then the currently focused element in the browser will be blur'ed whenever the popup is opened because the popup will be given focus.
• anchor: The anchor determines where to anchor the panel. Takes a chrome or content-space DOM element or null. Defaults to null (which means to positioning it in screen coordinates).
• align: Where and how to locate the panel. This is a string that consists of a description of the placement. For example, "bottom left with anchor top left". The string is always of the form "bottom/top/middle left/right/center with anchor bottom/top/middle left/right/center". Other offsets are handled via margin/padding in the style option. To have a centered panel in the middle of the screen, you'd {anchor: null, align: "middle center with anchor middle center"}.

The Panel Object

The Panel type is returned by a call to jetpack.panel.open(...). Once you have a Panel object, you can manipulate that panel in numerous ways.

Inherited

• All of the properties of the window object currently used by Firefox for panels?

Methods

• myPanel.close(): Closes the panel. All internal panel state is lost.
• myPanel.hide(): Hides the panel temporarily. If the window/object that the panel is anchored to moves while the panel is hidden, upon show it too has moved accordingly.
• myPanel.show(): Undoes the hide() operation.

Properties

• myPanel.contentDocument: A pointer to the content document of the rich data window being displayed in the panel.
• myPanel.contentWindow: A pointer to the containing window of the document being displayed by the panel.

Examples

This is an example extension to load the mobile version of Reddit in a panel, when a statusbar icon is clicked.

function openRedditPanel( anchor ){
  jetpack.panels.open({
    url: "http://m.reddit.com",
    anchor: anchor,
    align: "bottom right with anchor top right"
  });
}

jetpack.statusBar.append({
  html: "Reddit",
  onReady: function(widget) {
    $(widget).click(function(){
      openRedditPanel(widget);
    });
  },
});

Reference Material

From the XUL reference guide:

• Panels
• Opening/Closing Panels
• Position Panels