Mozilla Add-ons Community Blog
Categories: developers jetpack sdk

Just Landed: Simple Prefs API

2 responses

On November 28, Myk Melez closed pull request 270, which added the new ‘simple-prefs’ module to the Addon SDK. This addition to the SDK’s addon-kit apis is special for a couple of reasons:

  • The ability to add a simple preferences panel to an SDK-based add-on has been a major gap in functionality in the SDK. We’re very happy to be moving forward adding features like this.
  • This code was contributed entirely from the community, in particular community contributors Hernán Colmeiro and Erik Vold.

How to get it

As this API has not been included in an SDK release, it is not yet available in the online builder, so the only way you can try this out currently is by installing the SDK locally. The simple-prefs api is currently available by checking out the ‘master’ branch of the addon-sdk repository:

git clone git://github.com/mozilla/addon-sdk.git

By default you should have the ‘master’ branch. Alternatively you can just download a zip archive of the current master:

https://github.com/mozilla/addon-sdk/zipball/master

If you are not familar with how to work with the SDK, please see the installation documentation.

How to use it

Preference fields are defined in an add-on’s package.json file as an array called ‘preferences’ that contains objects that contain four allowed values: type, name, value and title. The api currently only supports three types: integer, bool and string. Here is an example package.json file that defines three prefrence fields, one for each type supported by the SDK:

{
    "name": "pref-example",
    "license": "MPL 1.1/GPL 2.0/LGPL 2.1",
    "author": "Jeff Griffiths ( jeff@canuckistani.ca )",
    "version": "0.1",
    "fullName": "pref-example",
    "id": "jid1-NYHGYVhOiA8sWA",
    "description": "a basic add-on",
    "preferences": [
        {
            "type": "string",
            "name": "stringPreference",
            "value": "this is the default string value",
            "title": "String Preference"
        },
        {
            "type": "bool",
            "name": "boolPreference",
            "value": true,
            "title": "Boolean Pref" 
        },
        {
            "type": "integer",
            "name": "intPreference",
            "value": 42,
            "title": "Integer Pref" 
        }
    ]
}

In your JavaScript code, simply require simple-prefs as you would any other api-kit module:

var prefSet = require("simple-prefs");

You can access any of your preferences as a property of prefSet.prefs by name:

var strPref = prefSet.prefs.stringPreference;

You can also assign handlers to run whenever a preference is changed:

// define a generic prefs change callback
function onPrefChange(prefName) {
    console.log("The " + prefName + 
        " preference changed, current value is: " + 
        prefSet.prefs[prefName]
    );
}

prefSet.on("stringPreference", onPrefChange);

The preferences are exposed to the user via the about:addons page by clicking the ‘preferences’ button on the Addons page:

Your preference settings are each displayed on the preferences panel for your add-on with type-sensitive entry fields:

I’ve provided a very simple working example on github:

https://github.com/canuckistani/sdk-simple-prefs

Remember, you can only use this code with the current master branch of the SDK! Make sure you’ve installed this version before you start hacking!

2 comments on “Just Landed: Simple Prefs API”

  1. John Nagle, Silicon Valley, CA wrote on

    What, no way to select options from a list? No radio buttons? No drop-down menus?

    This is far too weak. XUL add-ons have much more powerful options capabilities and add-ons use them. (See “https://developer.mozilla.org/en/XUL/preference”) SDK panels allow anything you can do in HTML. This is weaker than either.

    Encouraging add-on developers to express options as numeric and text boxes to be filled in will result in terrible user interfaces. There’s not even a provision for limiting input values.

    So please provide radio buttons and drop-down menus. If you can’t do that, just make the Options button open a Panel object and we’ll take it from there.

    1. Jeff Griffiths wrote on

      Hi John, thanks for the feedback.

      You’re not alone in thinking this, Erik has logged a few bugs recently to track this work:

      http://is.gd/8Nizlr

      The proposals include radio buttons, drop-downs and boolean groups. He’s also addressing my suggestion that the the prefs object be iterable!