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 both functional and presentational capabilities of their Jetpacks. Gadget abilities are the gateway to a large, uncharted mass of applications that can be developed in concert with the other useful tools provided by Jetpack.

Proposal

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
• html text/xml - 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)
• 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() - reload 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';
    }
});