FUEL/firstrun

Building a first run help/introduction for extensions

not included or planned to be included in FUEL yet

Requirements/Goals

1) Incredibly easy for the developer to use

  a) All intro content outside of extension script
  b) Single line of extension code to enable intro check

2) Incredibly easy for the content author to use

  a) no editing of extension specific xml, javascript, etc.
  b) Auto determine intro content by file enumeration (so that you can and and remove pages without editing code)

3) Must not depend on FUEL

4) Must be compatible with Mozilla 1.8 and 1.9

5) Support to multiple locale. The Wizard part of the UI has its locale. The content has locale meta-data so that the wizard picks the right view.

Design thoughts

I am thinking that the intro content should just live in a separate directory in the extension's jar and have the first run code use that well known location to populate its ui.

content/<extension_name>/firstrun/1.html
content/<extension_name>/firstrun/2.html
...
content/<extension_name>/firstrun/n.html

My thoughts on the UI would be something like:

-------------------------------
|                              |
| |--------------------------| |
| |                          | |
| |                          | |
| |                          | |
| |                          | |
| |                          | |
| |                          | |
| |                          | |
| |       Intro Content      | |
| |                          | |
| |                          | |
| |                          | |
| |                          | |
| |                          | |
| |                          | |
| |                          | |
| |--------------------------| |
|                              |
|  [ Prev ] [Next]  [Close]    |
|-------------------------------

The previous and next button should work as expected based on where the user is in the intro content files.

Current Implementation

The current implementation is exposed as an XPCOM service ( internal service singleton ) and the developer can access using XUL declarative markup.

Deployment and Requirements

• chrome://firstrun/content has to be enabled in your chrome.manifest ( or previously installed )
• Developer has to set configuration using declarative markup. It is possible to configure how to execute ( production mode, always forced firstrun ).

API for the Extension Developer

In the developer's extension overlay file it is necessary to set the firstrun XBL binding:

<?xml-stylesheet href="chrome://firstrun/content/bindings/firstrun.css" type="text/css"?>

Firstrun function can be invoked via using the firstrun element and its child configuration parameters:

<firstrun base="chrome://pinksearch/content/firstrun">
 <autoplay />
 <panel src="init.html"></panel>
</firstrun>

Description

• firstrun base to tell which base url to be used for the content
• panel element describes each panel to be added to the execution list.
• autoplay element describes how to play ( production mode, always forced, maybe some others

Architecture

• Firstrun installed means the Firstrun will initialize anyways after T miliseconds ( hardcoded so far )
• Firstrun service is invoked from the execution of the <firstrun /> element which has to be enabled via the CSS XBL binding.

Feedback and contribs

Firstrun operations with no UI (briank)

Example

If (firstrun)
{
  doThis();
}
else
{
  doThat();
}

Support to any content, not HTML content (ericj)

• not only HTML content. Yes this is correct. Our first run system should support any media content in terms of document display.

Last run (~ Gijs)

• To explore other aspects in the application life cycle, for example the lastRun case. Actually this case is a browser shutdown state. A lastrun would possibly be the uninstalling I guess. But anyways this is important feedback. From the aspect of the application life cycle, maybe in FUEL we could come up with some sort of marshall events from the system level.