preferences/service

We are planning to deprecate the use by Firefox add-ons of the techniques described in this document.

Don't use these techniques to develop new add-ons. Use WebExtensions instead.

If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions instead.

Add-ons developed using these techniques might not work with multiprocess Firefox (e10s), which is already the default in Firefox Nightly and Firefox Developer Edition, and will soon be the default in Beta and Release versions of Firefox. We have documentation on making your add-ons multiprocess-compatible, but it will be more future-proof for you to migrate to WebExtensions.

A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.

Unstable

Access the Preferences system in Firefox. This enables add-ons to get and set system-wide settings. These are the same preferences that are exposed to users in the about:config page.
 
preferences/service gives you full access to the preferences system. You can also use the simple-prefs module to access just the preferences for your own add-on and expose them to the user in the Add-on Manager.

Globals

Functions

set(name, value)

Sets the application preference name to value.

Parameters

name : string
Preference name.

value : string,number,boolean
Preference value.

Example:

var name = "extensions.checkCompatibility.nightly";
require("sdk/preferences/service").set(name, false);

get(name, defaultValue)

Gets the application preference name.

Parameters

name : string

defaultValue : string,number,boolean
Preference value.

Returns

string,number,boolean : Preference value, returns defaultValue if no preference is set, returns undefined if defaultValue is not provided.

Example:

var name = "extensions.checkCompatibility.nightly";
var nightlyCompatChk = require("sdk/preferences/service").get(name);

has(name)

Parameters

name : string
Preference name.

Returns

boolean : Returns whether or not the application preference name exists.

defaultValue

Example:

var name = "extensions.checkCompatibility.nightly";
if (require("sdk/preferences/service").has(name)) {
  // ...
}

keys(root)

Parameters

root : string
Preference root name.

Returns

array : Returns an array of strings representing the child preferences of the root of this branch.

isSet(name)

Parameters

name : string
Preference name.

Returns

boolean : Returns whether or not the application preference name both exists and has been set to a non-default value by the user (or a program acting on the user's behalf).

Example:

var name = "extensions.checkCompatibility.nightly";
if (require("sdk/preferences/service").isSet(name)) {
  // ...
}

reset(name)

Clears a non-default, user-set value from the application preference name. If no user-set value is defined on name, the function does nothing. If no default value exists the preference will cease to exist.

Parameters

name : string
Preference name.

Example:

var name = "extensions.checkCompatibility.nightly";
require("sdk/preferences/service").reset(name);

getLocalized(name, defaultValue)

Gets the localized value for an application preference name.

Parameters

name : string

defaultValue : string
Preference value.

Returns

string : Localized preference value, returns a default value if no preference is set. Some preferences refer to a properties file. So that prefs.get returns the properties file URL whereas prefs.getLocalized returns the value defined in the properties file.

Example:

var prefs = require("sdk/preferences/service");
var name = "general.useragent.locale";
prefs.get(name); // is equal to "chrome://global/locale/intl.properties"
prefs.getLocalized(name) // is equal to "en-US"

setLocalized(name, value)

Sets the localized application preference name to value.

Parameters

name : string
Preference name.

value : string
Preference value, a URL to a properties file

Example:

require("sdk/preferences/service").set("general.useragent.locale",
                                   "chrome://global/locale/intl.properties");

Example: Setting Global Preferences

var { get, set } = require("sdk/preferences/service");
var { when: unload } = require("sdk/system/unload");

var oldValue = get("browser.urlbar.autoFill");
set("browser.urlbar.autoFill", true);

// By AMO policy global preferences must be changed back to their original value
unload(function() {
  set("browser.urlbar.autoFill", oldValue);
});

Document Tags and Contributors

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