Labs/Jetpack/JEP/33

	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.

JEP 33 - Gadget

• Champion: Daniel Buchner <daniel@mozilla.com>
• Status: Concept
• Type: API Track
• Created: 2 Dec 2009
• Reference Implementation: new Gadget({options})
• JEP Index

Introduction and Rationale

Gadget for Jetpack is a crucial API enhancement that allows developers using the Jetpack extension development platform to extend the reach and scope of what is able to be accomplished with Jetpack. The magic of Gadget is the ability for developers to create what will appear to the user to be desktop applications with only HTML, JavaScript, and CSS.

Proposal

Each Gadget will be run in a separate OS process. Upon installation, the Jetpack will auto-create a shortcut for the Gadget in the Start Menu > Programs > Firefox Gadgets directory as well as an entry in the Jetpack Gadget Launcher (see screenshot for details).

 Outstanding Issues:
 * How does the add and remove Gadgets mechanism effect its changes?
 * What method will we use to start-up a Gadget (shortcut target param?)
 * What's the UI/user-flow for modifying settings and other user options. 

A new Gadget instantiation: new Gadget({options})

Where options is an object:

Properties

• title uri - Title that appears in the title bar of Gadget
• icon uri - icon to show in the title bar section of the Gadget
• desktopIcon uri - icon that will be used for the auto-created desktop shortcut
• html text/html - html content for the feature
• url uri - url to load content for the feature
• width num - initial width of the Gadget (defaults: 320px - standard smartphone width resolution)
• height num - initial height of the Gadget (defaults: 480px - standard smartphone height resolution)
• maxWidth num - maximum width of the Gadget
• maxHeight num - minimum width of the Gadget
• allowMaximize bool - specifies whether or not a Gadget will have the ability to maximize
• allowResize bool - specifies whether or not a user can resize a Gadget

Events

• onFocus func - event triggered when the Gadget is focused
• onBlur func - event triggered when the Gadget losses focus
• onReady func - event triggered when the Gadget is ready for manipulation or content injection
• onMinimize func - event triggered when the Gadget is minimized to the task bar
• onMaximize func - event triggered when the Gadget is maximized
• onRestore func - event triggered when the Gadget is restored from the task bar

 All events are passed the following property hash:
 * icon - a pointer to the icon used in the Gadget title bar.
   * icon.toDefault() - reloads icon to original icon
 * contentDocument - document element of the content area
 * position - an object that includes the Gadget's position on the screen: {x: 400, y: 500}
 * location - the URL of the Gadget's window object, http://, chrome://

Example

Show mozilla.com in a Gadget and change the background color of the document when clicked.

new Gadget({,
    url: "http://www.mozilla.com/",
    width: 300,
    onFocus: function(gadget) {
        gadget.contentWindow.document.body.style.background = '#ffffff';
    },
    onBlur: function(gadget){
        gadget.contentWindow.document.body.style.background = '#ff0000';
    }
});