simple-prefs


This module is currently experimental.

Based on the feedback we get from users, we expect to change it, and may need to make incompatible changes in future releases.

The simple-prefs module lets you 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.

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?"
    }]
}

Setting Attributes

Mandatory Common Attributes

These are attributes that all settings must have.

Attribute Description
type The type of setting, as defined in the "Setting Types" section below.
name

An identifier for the setting. This is used to access the setting from your add-on:

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

This means that it must be a valid JavaScript identifier.
title This is used as a label for the setting in the Add-ons Manager user interface.

Optional Common Attributes

These are attributes that all settings may have:

Attribute Description
description This appears below the setting title in the Add-ons Manager UI.
value A default value for the setting. Depending on the setting type, this may be an integer, string, or boolean value.

Setting-Specific Attributes

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

Setting Types

The setting types map to the inline settings types used by the Add-on Manager. All the inline settings are supported except for radio and menulist.

Type Description Example Specification
bool Displayed as a checkbox and stores a boolean. 
{
    "description": "Does it have tentacles?",
    "type": "bool",
    "name": "hasTentacles",
    "value": true,
    "title": "Tentacles"
}
boolint

Displayed as a checkbox and stores an integer.

A boolint is presented to the user as a checkbox, but instead of storing true or false, the "on" or "off" checkbox states are mapped to integers using "on" or "off" properties in the specification.

To provide this mapping the boolint requires two mandatory attributes called "on" and "off", both of which are supplied as strings.

Note that even so, the "value" property is supplied as an integer.

 
{
    "type": "boolint",
    "name": "myBoolint",
    "on": "1",
    "off": "2",
    "value": 1,
    "title": "My Boolint"
}
integer Displayed as a textbox and stores an integer. 
{
    "description": "How many eyes?",
    "type": "integer",
    "name": "eyeCount",
    "value": 8,
    "title": "Eye count"
}
string Displayed as a textbox and stores a string. 
{
    "type": "string",
    "name": "monsterName",
    "value": "Kraken",
    "title": "Monster name"
}
color Displayed as a colorpicker and stores a string in the #123456 format. 
{
    "type": "color",
    "name": "highlightColor",
    "value": "#6a5acd",
    "title": "Highlight color"
}
file Displayed as a "Browse" button that opens a file picker and stores the full path and name of the file selected. 
{
    "type": "file",
    "name": "myFile",
    "title": "Select a file"
}
directory Displayed as a "Browse" button that opens a directory picker and stores the full path and name of the directory selected. 
{
    "type": "directory",
    "name": "myDirectory",
    "title": "Select a directory"
}
control

Displays a button.

When the user clicks the button, the function listening to the on() function for this preference is called.

This type requires an mandatory attribute called "label" which is provided as a string. It is used to label the button.

In "package.json":

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

In "main.js":


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

API Reference

Functions

on(prefName, listener)

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

Example:

function onPrefChange(prefName) {
    console.log("The " + prefName + " preference changed.");
}
require("simple-prefs").on("somePreference", onPrefChange);
require("simple-prefs").on("someOtherPreference", onPrefChange);
prefName : String

The name of the preference to watch for changes.

listener : Function

The listener function that processes the event.

removeListener(prefName, listener)

experimental Unregisters an event listener for the specified preference.

prefName : String

The name of the preference to watch for changes.

listener : Function

The listener function that processes the event.

Properties

prefs : object

experimental A persistent object private to your add-on. Properties with boolean, number, and string values will be persisted in the Mozilla preferences system.