simple-prefs

Store preferences across application restarts. You can store booleans, integers, and string values, and users can configure these preferences in the Add-ons Manager. This gives users a consistent way to access and modify preferences across different add-ons.

This API is for your add-on's preferences. If you need to get and set the general browser preferences, use preferences/service.

Usage

Defining and initializing preferences

To define preferences and give them initial values, add a new JSON array called preferences to your package.json file, and give it one entry for each preference:

{
    "fullName": "Example Add-on",
    ...
    "preferences": [{
        "name": "somePreference",
        "title": "Some preference title",
        "description": "Some short description for the preference",
        "type": "string",
        "value": "this is the default string value"
    },
    {
        "description": "How many of them we have.",
        "name": "myInteger",
        "type": "integer",
        "value": 8,
        "title": "How Many?"
    }]
}

Each preference is defined by a group of attributes. There are:

• mandatory attributes that all preferences must have
• optional attributes
• attributes that are specific to the preference's data type

Mandatory Common Attributes

These are attributes that all preferences must have.

console.log(require("sdk/simple-prefs").prefs.mySettingName);

Optional Common Attributes

These are attributes that all preferences may have:

{
    "name": "myHiddenInteger",
    "type": "integer",
    "title": "How Many?",
    "hidden": true
}

Type-Specific Attributes

These are settings that are only applicable to certain preference types. They are documented along with the preference types themselves.

Preference Types

The setting types map to the inline settings types used by the Add-on Manager. All the inline preferences are supported.

{
    "description": "Does it have tentacles?",
    "type": "bool",
    "name": "hasTentacles",
    "value": true,
    "title": "Tentacles"
}

{ 
    "type": "boolint",
    "name": "myBoolint",
    "on": "1",
    "off": "2",
    "value": 1,
    "title": "My Boolint"
}

{
    "description": "How many eyes?",
    "type": "integer",
    "name": "eyeCount",
    "value": 8,
    "title": "Eye count"
}

{
    "type": "string",
    "name": "monsterName",
    "value": "Kraken",
    "title": "Monster name"
}

{
    "type": "color",
    "name": "highlightColor",
    "value": "#6a5acd",
    "title": "Highlight color"
}

{
    "type": "file",
    "name": "myFile",
    "title": "Select a file"
}

{
    "type": "directory",
    "name": "myDirectory",
    "title": "Select a directory"
}

{
    "name": "typeOfBreath",
    "type": "menulist",
    "title": "Type of breath",
    "value": 0,
    "options": [
        {
            "value": "0",
            "label": "Fire"
        },
        {
            "value": "1",
            "label": "Cold"
        },
        {
            "value": "2",
            "label": "Disintegration"
        }
    ]
}

{
    "name": "alignment",
    "type": "radio",
    "title": "Alignment",
    "value": "N",
    "options": [
        {
            "value": "L",
            "label": "Lawful"
        },
        {
            "value": "N",
            "label": "Neutral"
        },
        {
            "value": "C",
            "label": "Chaotic"
        }
    ]
}

{
    "type": "control",
    "label": "Click me!",
    "name": "sayHello",
    "title": "Say Hello"
}

var sp = require("sdk/simple-prefs");
sp.on("sayHello", function() {
  console.log("hello");
});

Localization

Using the SDK's localization system, you can provide translated forms of the title and description attributes. See the localization tutorial for more details.

Getting and setting preferences

Unless you've marked them as hidden, the user will be able to see and change the preferences in the Add-on Manager.

You can also see them and change them programmatically using the prefs property, and listen for changes to a preference using on().

Simple-prefs in the preferences system

Preferences defined using simple-prefs are stored in the Firefox preferences system alongside all the other preferences. This means that they're visible in about:config, and they can be accessed using the global simple-preferences module. By default, simple preferences are stored in a preference like:

extensions.<addon-id>.<preference-name>

For example, if you had a simple-pref named "somePreference" then you could get its value like so:

require('sdk/preferences/service').get(['extensions', require('sdk/self').id, 'somePreference'].join('.'))

This would give you the same value as:

require('sdk/simple-prefs').prefs['somePreference']

The branch of the preferences tree under which simple-prefs are stored is, by default, the add-on ID. Sometimes you might need to use a different branch, especially if you are porting an add-on to the SDK. You can change the sub-branch of extensions using the preferences-branch key in your add-on's package.json file.

Globals

Functions

on(prefName, listener)

Registers an event listener that will be called when a preference is changed.

The event listener may take an optional parameter that specifies the name of the property which changed.

Example:

function onPrefChange(prefName) {
  console.log("The preference " + 
              prefName + 
              " value has changed!");
}
require("sdk/simple-prefs").on("somePreference", onPrefChange);
require("sdk/simple-prefs").on("someOtherPreference", onPrefChange);

// `""` listens to all changes in the extension's branch
require("sdk/simple-prefs").on("", onPrefChange);

Parameters

prefName : String
The name of the preference to watch for changes.

listener : Function
The listener function that processes the event.

removeListener(prefName, listener)

Unregisters an event listener for the specified preference.

Parameters

prefName : String
The name of the preference to watch for changes.

listener : Function
The listener function that processes the event.

Properties

prefs

This property is an object containing the simple-prefs you have defined for your add-on. You can use it to access preference values and to change them. Suppose you've defined a preference like this:

  "preferences": [{
      "name": "somePreference",
      "title": "Some preference title",
      "description": "Some short description for the preference",
      "type": "string",
      "value": "this is the default string value"
  }]

You can access somePreference using the prefs property:

var preferences = require("sdk/simple-prefs").prefs;

console.log(preferences.somePreference);
preferences.somePreference = "this is a new value";

console.log(prefs["somePreference"]); // bracket notation
preferences["somePreference"] = "this is the default string value";

console.log: my-addon: this is the default string value
console.log: my-addon: this is a new value