Settings

Note: This page documents the Jetpack Prototype, which is no longer under active development. Read the experiment report for what we learned from it and the blog post announcing the first SDK release for what we're up to next!

The jetpack.storage.settings namespace allows jetpacks to specify user-configurable settings. Jetpack will automatically generate a user interface based on the specification. The settings persist across browser sessions and are stored using the Jetpack simple storage API. Settings are private to each jetpack and are not accessible by other jetpacks.

Because it is still under development, the API currently lives in the future and must be imported before it is used:

jetpack.future.import("storage.settings");

Specifying settings in a manifest

To specify its settings, a jetpack defines a variable named manifest in its global namespace before it imports the settings API. The value of this variable must be an object that contains a property named settings. The value of the settings property is an array of objects representing the settings to expose to users. Jetpack will automatically generate a user interface from this specification that users of your jetpack may use to customize the settings. The user can open this interface from the "settings" button next to your jetpack on the "Installed Features" tab of the about:jetpack page.

Here is an example manifest definition:

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 }
  ]
};

// Import after defining manifest!
jetpack.future.import("storage.settings");

This definition will result in a user interface with an input field for each setting defined above.

With the above manifest the following stored properties are available in the jetpack's code:

  • jetpack.storage.settings.twitter.username
  • jetpack.storage.settings.twitter.password
  • jetpack.storage.settings.facebook.username
  • jetpack.storage.settings.facebook.password
  • jetpack.storage.settings.music
  • jetpack.storage.settings.volume

See also