devtools/docs/contributor/preferences.md

   1 # Preferences
   2
   3 This documentation aims at giving an overview of the preferences API used in DevTools, it
   4 is not an actual documentation about the list of preferences available in DevTools.
   5
   6 ## Overview
   7
   8 Preferences allows you to save and read strings, numbers, booleans to the preferences
   9 store, which is tied to a profile. A preference can also have a default value.
  10
  11 The technical solution for handling preferences differs depending whether you are
  12 testing DevTools as Firefox panel, or a standalone tool running with Launchpad.
  13
  14 ## Preference types
  15
  16 DevTools relies on nsIPrefBranch for preferences, which supports different types of
  17 preferences:
  18 * `Int`
  19 * `Boolean`
  20 * `Char`
  21 * `String`
  22
  23 Choose the appropriate type depending on the data you need to store. If you need to store
  24 a JavaScript object or array, the recommended way is to:
  25 * use a `String` type preference
  26 * use JSON.stringify to save
  27 * use JSON.parse to read
  28
  29 Note that nsIPrefBranch also supports a `Complex` type, but this type is not supported
  30 when running in Launchpad.
  31
  32 ## Reading and updating preferences
  33
  34 ### API docs for nsIPrefBranch and nsIPrefService
  35
  36 DevTools relies on Services.pref to handle preferences. You can access the API docs for
  37 this service at:
  38 * [Source for nsIPrefBranch](https://searchfox.org/mozilla-central/source/modules/libpref/nsIPrefBranch.idl)
  39 * [Source for nsIPrefService](https://searchfox.org/mozilla-central/source/modules/libpref/nsIPrefService.idl)
  40
  41 If you are using Launchpad, note that only a subset of nsIPrefService methods are
  42 implemented (addObserver and removeObserver). Launchpad relies on a Services shim file
  43 provided by devtools-module ([code on GitHub](https://github.com/firefox-devtools/devtools-core/blob/master/packages/devtools-modules/src/Services.js)).
  44
  45 ### Services.pref.get* and Services.pref.set*
  46
  47 The main APIs you will have to know and use are getters and setters.
  48 * `Services.pref.getIntPref(prefName, defaultValue);` This method will throw if the
  49 preference cannot be found and you didn't pass a default value!
  50 * `Services.pref.setIntPref(prefName, prefValue)` This method will throw if the provided
  51 value does not match the preference type!
  52
  53 These APIs are very similar for each preference type.
  54
  55 ## Create a new preference
  56
  57 Debugger-specific preferences should go in
  58 devtools/client/preferences/debugger.js. Beyond that, most new preferences
  59 should go in browser/app/profile/firefox.js, which is for desktop Firefox only.
  60 If a preference should be available even when the client for DevTools is not
  61 shipped (for instance on Fennec) it should go in modules/libpref/init/all.js,
  62 which is for preferences that go in all products.
  63
  64 ### Projects using Launchpad
  65
  66 At the time of writing this doc, projects using Launchpad have to duplicate the default
  67 definition of a preference.
  68 * debugger.html: update [src/utils/prefs.js](https://github.com/firefox-devtools/debugger.html/blob/master/src/utils/prefs.js)
  69 * netmonitor: update [index.js](http://searchfox.org/mozilla-central/source/devtools/client/netmonitor/index.js)
  70 * webconsole: update [local-dev/index.js](http://searchfox.org/mozilla-central/source/devtools/client/webconsole/local-dev/index.js)
  71
  72 ## Inspect preferences
  73
  74 Depending on the project you are working on, preferences are stored differently but can
  75 always be inspected.
  76
  77 In Firefox, you can open a tab to about:config and search by preference name.
  78
  79 In Launchpad, preferences are actually saved to localStorage. Open DevTools on your
  80 Launchpad application and inspect the local storage content. You should see entries
  81 prefixed by `Services.prefs:`. You will only see preferences where a user-specific value
  82 has overridden the default value.