Labs/Jetpack/Reboot/JEP/105: Difference between revisions

← Older edit

Labs/Jetpack/Reboot/JEP/105 (view source)

Revision as of 22:36, 6 May 2010

4 bytes removed , 6 May 2010

→‎API

Dietrich

Confirmed users, Bureaucrats and Sysops emeriti

2,088

edits

@@ Line 2: / Line 2: @@
 * Champion: Aza Raskin - aza@mozilla.com
-* Status: Accepted/In-Queue
+* Peeps: Dietrich Ayala, Myk Melez
-* Bug Ticket:
+* Status: Implementation in Progress
+* Bug Ticket: {{bug|549324}}
 * Type: API
-* Difficulty: 4
 === Proposal ===
-This JEP describes an API for handling the life-cycle of Jetpacks. In particular, it gives a Jetpack methods for registering event handlers for various install and uninstall states.
+This JEP describes an API for handling the life-cycle of add-ons. In particular, it provides callback APIs for responding to various install and uninstall events.
-In addition to the event handlers, it provides a more declarative format.
-==== Events ====
-All methods of an add-on introspecting and interacting with its environmental metas using the Jetpack API live in the "me" module.
+==== API ====
-The event handlers can be used as follows:
+All methods involving introspection and interaction with an add-on's environment live in the "self" module.
 <pre class="brush:js;">
-me = require("me");
+let self = require("self");
-// eventName is one of install
+self.onInstall( function )
-me.bind(eventName, callback);
+self.onUpgrade( function )
-// These are potential convenience functions
+self.onUninstall( function )
-me.onInstall( function )
 </pre>
-The <code>me.onInstall</code> gets called on the first run of an extension. If an extension is uninstalled and reinstalled it gets called again (as the act of uninstalling removes all data associated with the add-on).
+The <code>onInstall</code> handler gets called on the first run of an extension. If an extension is uninstalled and reinstalled it gets called again (as the act of uninstalling removes all data associated with the add-on). <code>onUpgrade</code> get's called when an extension is upgraded.
-There does not seem to be a strong use-case for allowing for event handlers that act upon disabling, enabling, and un-installing an extension.
-==== Declarative ====
-The first-run experience is coded inside of <code>manifest.json</code>, the feature's manifest, which is (not un-coincidentally) where the settings are placed.
-<pre class="brush:js;">
-manifest = {
-  installPage: stringOrXml,
-  uninstallPage: stringOrXml
-}
-</pre>
-=== Difficulty ===
-Rating: '''Easy'''
-=== Key Issues ===
-* enable/disable?
-* when is it run?
-=== Dependencies & Requirements ===
+Nothing is passed to the <code>onInstall</code> handler. An object which contains version info for the add-on prior to being updated gets passed to <code>onUpgrade</code>.
-* Dependent on JEP 106
+The <code>onUninstall</code> handler is called when the add-on is uninstalled, giving add-ons the opportunity to clean up files, preferences, annotations <strike>or to flip the bird at the user on the way out</strike>.
-=== Internal Methods ===
+'''Enable/Disable'''
-* What methods, mechanisms, or resources does this provide internally within the Jetpack platform code.
+There's no need for explicit support for enabling and disabling of add-ons here. When an add-on is disabled, any callbacks the code registered with require("unload").when() or require("unload").ensure() are automatically called, and when an addon is enabled, its code is re-evaluated and its exports.main() is called.
 === Use Cases ===
@@ Line 67: / Line 39: @@
 * Show a set of tooltips for the UI that an extension has added, in vivo to the interface.
 * Give a survey when you uninstall an add-on.
+* Clean up preferences, files, annotations, when you uninstall an add-on.