Labs/Jetpack/JEP/33: Difference between revisions

Latest revision as of 18:52, 29 December 2009

	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';
    }
});

@@ Line 1: / Line 1: @@
 {{draft}}
-== JEP 33 - Window ==
+== JEP 33 - Gadget ==
 * Champion: Daniel Buchner <daniel@mozilla.com>
@@ Line 7: / Line 7: @@
 * Type: API Track
 * Created: 2 Dec 2009
-* Reference Implementation: jetpack.addElement('window')
+* Reference Implementation: new Gadget({options})
 * [[Labs/Jetpack/JEPs|JEP Index]]
 === Introduction and Rationale ===
-Window 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. Window 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.
+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 ===
-A new Window instantiation:
+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).
-<code>jetpack.addElement('window', {options})</code>
-Where <tt>options</tt> is a property hash:
+  Outstanding Issues:
-* <tt>icon</tt> <i>uri</i> - icon to show in the title bar section of the window
+  * How does the add and remove Gadgets mechanism effect its changes?
-* <tt>html</tt> <i>text/xml</i> - html content for the feature
+  * 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:
+<code>new Gadget({options})</code>
+Where <tt>options</tt> is an object:
+Properties
+* <tt>title</tt> <i>uri</i> - Title that appears in the title bar of Gadget
+* <tt>icon</tt> <i>uri</i> - icon to show in the title bar section of the Gadget
+* <tt>desktopIcon</tt> <i>uri</i> - icon that will be used for the auto-created desktop shortcut
+* <tt>html</tt> <i>text/html</i> - html content for the feature
 * <tt>url</tt> <i>uri</i> - url to load content for the feature
-* <tt>width</tt> <i>num</i> - initial width of the Window (320 - standard smartphone width resolution)
+* <tt>width</tt> <i>num</i> - initial width of the Gadget (defaults: 320px - standard smartphone width resolution)
-* <tt>height</tt> <i>num</i> - initial height of the Window (480 - standard smartphone height resolution)
+* <tt>height</tt> <i>num</i> - initial height of the Gadget (defaults: 480px - standard smartphone height resolution)
-* <tt>persist</tt> <i>bool</i> - will the Window stay open when a user closes the browser instance?
+* <tt>maxWidth</tt> <i>num</i> - maximum width of the Gadget
-* <tt>onFocus</tt> <i>func</i> - event triggered when the Window is focused
+* <tt>maxHeight</tt> <i>num</i> - minimum width of the Gadget
-* <tt>onBlur</tt> <i>func</i> - event triggered when the Window losses focus
+* <tt>allowMaximize</tt> <i>bool</i> - specifies whether or not a Gadget will have the ability to maximize
-* <tt>onReady</tt> <i>func</i> - event triggered when the Window's content is loaded and ready for manipulation.
+* <tt>allowResize</tt> <i>bool</i> - specifies whether or not a user can resize a Gadget
+Events
+* <tt>onFocus</tt> <i>func</i> - event triggered when the Gadget is focused
+* <tt>onBlur</tt> <i>func</i> - event triggered when the Gadget losses focus
+* <tt>onReady</tt> <i>func</i> - event triggered when the Gadget is ready for manipulation or content injection
+* <tt>onMinimize</tt> <i>func</i> - event triggered when the Gadget is minimized to the task bar
+* <tt>onMaximize</tt> <i>func</i> - event triggered when the Gadget is maximized
+* <tt>onRestore</tt> <i>func</i> - event triggered when the Gadget is restored from the task bar
-All events are passed the following property hash:
+  All events are passed the following property hash:
-* <tt>icon</tt> - a pointer to the icon used in the Window title bar.
+  * <tt>icon</tt> - a pointer to the icon used in the Gadget title bar.
-** <tt>icon.default()</tt> - reload icon to original icon
+    * <tt>icon.toDefault()</tt> - reloads icon to original icon
-* <tt>contentDocument</tt> - document element of the content area
+  * <tt>contentDocument</tt> - document element of the content area
-* <tt>position</tt> - an object that includes the Window's position on the screen: {x: 400, y: 500}
+  * <tt>position</tt> - an object that includes the Gadget's position on the screen: {x: 400, y: 500}
-* <tt>location</tt> - the URL of the window, http://, chrome://
+  * <tt>location</tt> - the URL of the Gadget's window object, http://, chrome://
 === Example ===
-Show mozilla.com in a Window and change the background color of the document when clicked.
+Show mozilla.com in a Gadget and change the background color of the document when clicked.
 <pre class="brush:js;toolbar:false;">
-jetpack.addElement('window',
+new Gadget({,
      url: "http://www.mozilla.com/",
      width: 300,
-     onFocus: function(window) {
+     onFocus: function(gadget) {
-         window.contentWindow.document.body.style.background = '#ffffff';
+         gadget.contentWindow.document.body.style.background = '#ffffff';
      },
-     onBlur: function(){
+     onBlur: function(gadget){
-         window.contentWindow.document.body.style.background = '#ff0000';
+         gadget.contentWindow.document.body.style.background = '#ff0000';
      }
 });
 </pre>

Labs/Jetpack/JEP/33: Difference between revisions

Latest revision as of 18:52, 29 December 2009

Contents

JEP 33 - Gadget

Introduction and Rationale

Proposal

Example

Navigation menu

Labs/Jetpack/JEP/33: Difference between revisions

Latest revision as of 18:52, 29 December 2009

JEP 33 - Gadget

Introduction and Rationale

Proposal

Example

Navigation menu

Search