firefox-main/devtools/docs/contributor/preferences.md

Source code

Revision control

Copy as Markdown

Other Tools

# Preferences
This documentation aims at giving an overview of the preferences API used in DevTools, it
is not an actual documentation about the list of preferences available in DevTools.
## Overview
Preferences allows you to save and read strings, numbers, booleans to the preferences
store, which is tied to a profile. A preference can also have a default value.
## Preference types
DevTools relies on nsIPrefBranch for preferences, which supports different types of
preferences:
* `Int`
* `Boolean`
* `Char`
* `String`
Choose the appropriate type depending on the data you need to store. If you need to store
a JavaScript object or array, the recommended way is to:
* use a `String` type preference
* use JSON.stringify to save
* use JSON.parse to read
Note that nsIPrefBranch also supports a `Complex` type.
## Reading and updating preferences
### API docs for nsIPrefBranch and nsIPrefService
DevTools relies on Services.pref to handle preferences. You can access the API docs for
this service at:
### Services.pref.get* and Services.pref.set*
The main APIs you will have to know and use are getters and setters.
* `Services.pref.getIntPref(prefName, defaultValue);` This method will throw if the
preference cannot be found and you didn't pass a default value!
* `Services.pref.setIntPref(prefName, prefValue)` This method will throw if the provided
value does not match the preference type!
These APIs are very similar for each preference type.
## Create a new preference
Debugger-specific preferences should go in
devtools/client/preferences/debugger.js. Beyond that, most new preferences
should go in browser/app/profile/firefox.js, which is for desktop Firefox only.
If a preference should be available even when the client for DevTools is not
shipped (for instance on Fennec) it should go in modules/libpref/init/all.js,
which is for preferences that go in all products.
## Inspect preferences
Depending on the project you are working on, preferences are stored differently but can
always be inspected.
In Firefox, you can open a tab to about:config and search by preference name.