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

1,377 bytes added , 6 May 2010

→‎API

Dietrich

Confirmed users, Bureaucrats and Sysops emeriti

2,088

edits

@@ Line 1: / Line 1: @@
-== JEP 105 - First-Run ==
+== JEP 105 - Life-cycle ==
 * 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 add-ons. In particular, it provides callback APIs for responding to various install and uninstall events.
+==== API ====
+All methods involving introspection and interaction with an add-on's environment live in the "self" module.
-=== Proposal ===
+<pre class="brush:js;">
-* What will it do?
+let self = require("self");
-* What does it enable internally/externally?
-* How hard is it to implement?
+self.onInstall( function )
+self.onUpgrade( function )
-=== Key Issues ===
+self.onUninstall( function )
+</pre>
+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.
-=== 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 ===
-=== API Methods ===
+* Show a welcome page/tutorial when you install an add-on.
-* What are the pretty API wrapped methods externally exposed to Jetpack developers?
+* 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.