Labs/Jetpack/JEP/30

	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 30 - First-run Help

• Champion: Aza Raskin <aza at mozilla dot com>
• Editors: Drew <drew at mozilla dot com>
• Status: Implementing
• Type: API Track
• Created: 17 Nov 2009
• Reference Implementation: None
• Relevant Bugs:
• JEP Index

Introduction and Rationale

This JEP describes an API for creating first-run pages for Jetpacks.

After installing a Jetpack, without some sort of instructions on how to use the features just installed, the user can feel lost, bewildered, and confused. The first-time experience is exactly when users need the greatest reassurance and instruction, which is why so many Firefox add-ons create a first-run page to explain and guide the user through the new functionality. With Jetpacks, we have the opportunity to create a more unified feel.

Object-based Help

Enabling support for teaching people how to use specific UI-features in Jetpack is important to making the onramp for new feature adoption shallow. One way of doing this is have first-run documentation (and potentially later-on help) be displayed as close as possible to the interaction points, for instance as dismissible tooltips.

Take the example of a status-bar icon. During install, instead of writing a full HTML-based page that has to duplicate, with screenshots, how the status-bar looks (which isn't immune to getting out of date when the platform changes, or for appearing with the wrong OS look-and-feel) we can have Jetpack just put the one or two lines of help right there.

In code, this would be written in the same place as your definition of the UI element:

jetpack.statusBar.append({
  url: "graph.html",
  onReady: function(){ ... },
  help: "I'm your personal tab-user grapher...",
});

These messages are shown/or are accessible from from:

• On first run, these messages get shown.
• All visual UI elements will also have a context-menu option of "Help" which will bring up the message.
• Every Jetpack listed on the installed page will have link/button that will cause the messages to re-open.

If it turns out that these messages are annoying or too much, we will add the ability to, from the manifest, suppress these messages.

Hidden Elements

Some Jetpacks only expose UI through elements that are hidden by default (a context menu) or that do not have a visual representation (a pageMod). We need a way of handling these edge-cases.

Firefox will soon have a browser button (AKA the Tools button):

At that point, we can have all non-visible UI help concatenated and displayed through a bubble that points to the browser button. For now, however, we can have the bubble appear from the site-badge button.

This example corresponds to the following code:

jetpack.menu.context.page.add({
  icon: "http://...",
  label: "Inject jQuery",
  help: "Right-click any ... <img src='...'/>",
  command: function(){ ... }
});

jetpack.pageMods.add( callback, {
  matches: "*",
  help: "As it loads, check every website..."
});

Creating a First-run Page

First-run will live at jetpack.manifest.

The first-run experience is coded inside of the manifest, which is (not un-coincidentally) where the settings are placed.

jetpacks.manifest = {
  firstRun: options
}

options: {html: "

", url: "http://", text: "", img: "http://" } or html/url/img-url (a url is uniquely identifiable by starting with "http://" that doesn't end in an three-letter image extension).

• Want to take care of the case where it's just some text. Just a single image. A full HTML page.
• Want to take care of settings. Both as a link which pops open the goodness (jetpack.settings.open) and as something which is embedded (
  ) and as something which is in-flowed <input class="jetpack-setting" id="twitter.id"/>.

Interaction with Settings

One of the standard use cases for the first-run page—besides pedagogical—will be to setup up the Jetpack's settings. There are three ways of doing this:

1. Allow calling jetpack.settings.open() from the first-run page. (Although jetpack.settings.open is not yet implemented.)
2. Embed the settings in the first-run page (see below)
3. Inline inclusion of settings (see below).

Embedding the Settings

Embedding the settings into the first run-page is as simple as including a special id'ed tag,

, which automatically gets interpolated into the settings widget.

Inline Inclusion

Inline inclusion involves two things. The first is that we expose jetpack.storage.settings to the first-run webpage. This way, the page has full power to change and update the settings as it wishes, with whatever UI it desires.

The second is that we add a convenience method built on top of that functionality. If an DOM element has an ID matching a setting in the manifest, we store its value automatically into the settings.

For instance,

<b>Twitter Name:</b>
<input type="text" id="jetpack.storage.settings.twitterName"/>

Which works if twitterName was defined in the manifest. Otherwise an warning is logged to the console.

Note: This convenience method only works for values which don't require sanitization (like numerical inputs) until we have an implementation of HTML5 forms.

Multiple Jetpacks

FOR FUTURE IMPLEMENTATION

One of the pain points in original-flavor extensions has been that bundling two or more extensions together leads to a jarring experience on installation—numerous first-run pages pop-up like zits on a teenagers face after an oil bath.

With the Jetpack method of doing first-run pages, we can more easily intercept these first-run pages in the case of a bundle and create a unified experience.