From MozillaWiki
< Labs‎ | Jetpack‎ | JEP
Jump to: navigation, search

JEP 24 - Settings


Jetpacks would benefit from a simple way for their users to configure them. Common configuration use cases include minor visual/functional tweaks and account credentials for jetpacks that integrate with services. The basic idea is to make it as easy as possible for jetpacks to provide an interface for users to configure their settings.

We propose an API whereby jetpacks can specify their user-configurable settings, and Jetpack automatically generates a user interface based on the specification. The API will allow jetpacks to specify different types of settings, and the types are interface-agnostic, separating view from control logic such that Jetpack is not bound to a single user-facing representation of any given type, which means that Jetpack can continue to innovate on user interfaces for settings configuration in the future without requiring authors to update their setting specifications.

Settings persist across browser sessions and are stored using the Jetpack storage API. Settings are jetpack-specific and are not accessible by other jetpacks.


Accessing Settings

Settings are stored in the object and are accessible to jetpacks via simple object retrieval and assignment.

If you get a setting that the user hasn't set, but you've specified a default value for the setting, you'll get the default value.

If you access a password setting, and the user has a master password, and they haven't yet entered the master password for the current browsing session, they'll be prompted to enter their master password.

Specifying Settings in a Manifest

To specify its settings, a jetpack includes a top-level manifest object with a settings property whose value is an array of objects representing the setting groups and settings to expose to users. When a user configures the jetpack, Jetpack will generate an interface for doing so based on this specification.

For example, the following code:

var manifest = {
  settings: [
      name: "twitter",
      type: "group",
      label: "Twitter",
      settings: [
        { name: "username", type: "text", label: "Username" },
        { name: "password", type: "password", label: "Password" }
      name: "facebook",
      type: "group",
      label: "Facebook",
      settings: [
        { name: "username", type: "text", label: "Username", default: "jdoe" },
        { name: "password", type: "password", label: "Secret" }
    { name: "music", type: "boolean", label: "Music", default: true },
    { name: "volume", type: "range", label: "Volume", min: 0, max: 10, default: 5 }

might result in the following interface:

+ Twitter -------------+
| Username: [        ] |
| Password: [        ] |

+ Facebook ------------+
| Username: [ jdoe   ] |
| Secret:   [        ] |

  [x] Music
  Volume: [----|----]

and the following stored properties:


Setting Objects

Setting objects have the following properties:

The name of the setting. Required. It must be unique within a group of settings for a jetpack. It will be used as a property name in the object.
The kind of values the setting can store. Required.
A human-readable descriptive term identifying the setting. Required. It will be displayed in the user interface. Future support for localization of jetpacks might alter the usage or behavior of this property.
The default value of the setting. Optional.

Setting Types

While there are numerous potential setting types (think dates, autocomplete fields, multiselect fields, etc.) we'll start with the following restricted set:

a group of settings
a setting that is either true or false
a string of characters
a number
a string that should be treated as a password or other confidential information
a number within two bounds
a value from a set of possible values

Settings of certain types have additional properties.


The group type has the following additional properties:

An array of the setting objects contained by the group. Required.

The boolean type has the following additional properties:

A human-readable descriptive term identifying the true value. Optional.
A human-readable descriptive term identifying the false value. Optional.

The text type has no additional properties.


The number type has no additional properties.


Values for the password type are stored in Firefox's password manager, although they are accessible as properties on the settings store object. If a user uses a master password, and they haven't entered it yet during the current browsing session, they will be prompted to enter it when a jetpack retrieves a password from the settings store object.


The range type has the following additional properties:

the minimum value of the setting. Optional. Default value is 0.
the maximum value of the setting. Optional. Default value is 100.
the discrete amount by which the setting changes. Optional. Default value is 1.

The member type has the following additional properties:

An array of the possible values. Required.

Jetpacks can display their setting interface to users by calling

Access Points

The setting interface will be accessible to users via the following access points:

  • the context menu for a jetpack, which users see when they context-click on its visible UI
  • any element of the jetpack itself that calls
  • an option in the install list:


  • embedded in the first-run page (at least linked from the first-run page)?

Future Ideas

  • dependencies
  • callbacks
  • the ability to disable/enable settings
  • input validation
  • a mechanism for jetpacks to modify each others' settings (with permission)
  • putting the specification into a manifest instead of requiring an API call
  • HTML-based settings
  • custom CSS

HTML-based Settings

Any HTML element in a first-run page or in a block of HTML in the settings page that has an class of "setting" will have its value stored in the jetpack's settings. The id is taken as the setting name. Periods are used to indicate heiarchy. For example: id="Twitter.User name" can be accessed via["Twitter"]["User name"].


<div>User name: <input type="text" id="twitter.User name" class="setting"></div>

Custom CSS

settings.setup("big.css", {
  "Flavor": ["Chocolate", "Vanilla", "Matcha"], 
  "Color": {value:["Red", "Greed", "Mauve"], class="big"},
  "Name": {type:"text", style:"font-weight:bold;"}

Which injects big.css into the HTML representation of the settings (as well as the inline-styles).

If you want to define your own HTML for a settings page:


Then you just have HTML with appropriately id's and class's names (see below).