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

From MozillaWiki
< Labs‎ | Jetpack‎ | Reboot‎ | JEP
Jump to navigation Jump to search
Line 2: Line 2:


* Champion: Aza Raskin - aza@mozilla.com
* Champion: Aza Raskin - aza@mozilla.com
* Status: Under Review
* Peeps: Dietrich Ayala, Myk Melez
* Bug Ticket:
* Status: Implementation in Progress
* Bug Ticket: {{bug|549324}}
* Type: API
* Type: API
* Difficulty: 4


=== Proposal ===
=== 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.
==== API ====


==== Events ====
All methods involving introspection and interaction with an add-on's environment live in the "self" module.


All methods of an add-on introspecting and interacting with its environmental metas using the Jetpack API live in the "me" module.
<pre class="brush:js;">
let self = require("self");


The event handlers can be used as follows:
self.onInstall( function )


<pre class="brush:js;">
self.onUpgrade( function )
me = require("me");


// eventName is one of install, upgrade
self.onEnable( function )
me.bind(eventName, callback);


self.onDisable( function )


// These are potential convenience functions
self.onUninstall( function )
me.onInstall( function )
me.onUpgrade( function )
</pre>
</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). <code>me.onUpgrade</code> get's called when an extension is upgraded.
The <code>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). <code>onUpgrade</code> get's called when an extension is upgraded.


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>.
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>.


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.
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>.
 
==== 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>
 
<code>installPage</code> is shown after the extension has been instantiated, so has access to settings and version info.
 
<code>uninstallPage</code> is shown before the extension has been removed, so has access to settings and version info.
 
=== Difficulty ===
 
Rating: '''Easy'''
 
=== Key Issues ===
 
* enable/disable?
* when is it run?
 
=== Dependencies & Requirements ===
* Dependent on [[Labs/Jetpack/Reboot/JEP/106|JEP 106 - Registered Jetpack URLs]]


=== Internal Methods ===
Now that an add-on can be enabled and disabled without an application restart, add-ons should cleanly stop work (shut down page-workers, kill timers,
* What methods, mechanisms, or resources does this provide internally within the Jetpack platform code.
close streams) when they're disabled. They can do this via the <code>onDisable</code> handler. Conversely an add-on can kick it's services back into gear when it's enabled with the <code>onEnable</code> handler.


=== Use Cases ===
=== Use Cases ===
Line 73: Line 43:
* Show a set of tooltips for the UI that an extension has added, in vivo to the interface.
* 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.
* Give a survey when you uninstall an add-on.
* Clean up preferences, files, annotations, when you uninstall an add-on.

Revision as of 17:44, 6 May 2010

JEP 105 - Life-cycle

  • Champion: Aza Raskin - aza@mozilla.com
  • Peeps: Dietrich Ayala, Myk Melez
  • Status: Implementation in Progress
  • Bug Ticket: bug 549324
  • Type: API

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. 

let self = require("self");

self.onInstall( function )

self.onUpgrade( function )

self.onEnable( function )

self.onDisable( function )

self.onUninstall( function )

The onInstall 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). onUpgrade get's called when an extension is upgraded.

Nothing is passed to the onInstall handler. An object which contains version info for the add-on prior to being updated gets passed to onUpgrade.

The onUninstall handler is called when the add-on is uninstalled, giving add-ons the opportunity to clean up files, preferences, annotations or to flip the bird at the user on the way out.

Now that an add-on can be enabled and disabled without an application restart, add-ons should cleanly stop work (shut down page-workers, kill timers, close streams) when they're disabled. They can do this via the onDisable handler. Conversely an add-on can kick it's services back into gear when it's enabled with the onEnable handler.

Use Cases

  • Show a welcome page/tutorial when you install an add-on.
  • 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.
Retrieved from "https://wiki.allizom.org/index.php?title=Labs/Jetpack/Reboot/JEP/105&oldid=221239"