Your Search Results

    simple-prefs

    Experimental

    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.

    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 with 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.

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

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

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

    This means that it must be a valid JavaScript identifier.

    title This is used as a label for the preference in the Add-ons Manager user interface.

    Optional Common Attributes

    These are attributes that all preferences may have:

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

    A boolean value which, if present and set to true, means that the preference won't appear in the Add-ons Manager interface, so users of your add-on won't be able to see or alter it.

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

    Your add-on's code will still be able to access and modify it, just like any other preference you define.

    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.

    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"
    }
    menulist

    Displayed as a drop-down list. The type of the stored value depends on the default value.

    The options are specified by a mandatory "options" attribute, that is an array of objects with mandatory attributes "label" and "value"

     

    The values of the "value" attributes must be supplied as strings.

    The values of the "label" attributes prefixed with "{name}_options.", where {name} is the name of the preference, are used as localization keys. If no matching entries are found, the value of the "label" attributes is used verbatim as labels.

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

    Displayed as radio buttons. The type of the stored value depends on the default value.

    The options are specified by a mandatory "options" attribute, that is an array of objects with mandatory attributes "label" and "value"

     

    The values of the "value" attributes must be supplied as strings.

    The values of the "label" attributes prefixed with "{name}_options.", where {name} is the name of the preference, are used as localization keys. If no matching entries are found, the value of the "label" attributes is used verbatim as labels.

    {
        "name": "alignment",
        "type": "radio",
        "title": "Alignment",
        "value": "N",
        "options": [
            {
                "value": "L",
                "label": "Lawful"
            },
            {
                "value": "N",
                "label": "Neutral"
            },
            {
                "value": "C",
                "label": "Chaotic"
            }
        ]
    }
    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("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 ability to change the default preferences branch is new in Add-on SDK 1.15.

    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 branch 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.

    Example:

    function onPrefChange(prefName) {
        console.log("The " + prefName + " preference 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 prefs = require("sdk/simple-prefs").prefs;
    
    console.log(prefs.somePreference);
    prefs.somePreference = "this is a new value";
    console.log(prefs.somePreference);
    console.log: my-addon: this is the default string value
    console.log: my-addon: this is a new value
    

    Document Tags and Contributors

    Contributors to this page: wbamberg
    Last updated by: wbamberg,