configs/arch-config/.mozilla/firefox/default-release/chrome/docs/Preference.md
2022-05-11 21:19:02 +02:00

9.2 KiB

Preference

Table of Contents

Basics

Related Docs

Key/Value

  • Key:
    • Pref name
    • Type: 8-bit string
    • Convention is to use a dotted segmented form (Ex. browser.cache.disk.enable)
  • Value:
    • Type: bool, 32-bit ints, 8-bit C string
    • When you need an float, use a string. (Ex. general.smoothScroll.currentVelocityWeighting: "0.25")

Main Purpose

  • Feature enable/disable flags (Ex. xpinstall.signatures.required).
  • User preferences (Ex. things set from about:preferences)
  • Internal application parameters (Ex. javascript.options.mem.nursery.max_kb).
  • Application data (Ex. browser.onboarding.tour.onboarding-tour-addons.completed, services.sync.clients.lastSync).
  • Things that might need locking in an enterprise installation.

Preference file RFC

Key information on the sets that can be used in the configuration file.

  • pref(): Set default pref
    • sticky attr: same as sticky_pref()
    • locked attr: cannot change from default.
  • sticky_pref(): Always logged even if the defaults match
  • user_pref(): Set user pref

The following is a method of operating the configuration file parser.
See EBNF(Extended Backus-Naur form) if you want to know about syntax.

<pref-file>   = <pref>*
<pref>        = <pref-spec> "(" <pref-name> "," <pref-value> <pref-attrs> ")" ";"
<pref-spec>   = "user_pref" | "pref" | "sticky_pref" // in default pref files
<pref-spec>   = "user_pref"                          // in user pref files
<pref-name>   = <string-literal>
<pref-value>  = <string-literal> | "true" | "false" | <int-value>
<int-value>   = <sign>? <int-literal>
<sign>        = "+" | "-"
<int-literal> = [0-9]+ (and cannot be followed by [A-Za-z_])
<string-literal> =
  A single or double-quoted string, with the following escape sequences
  allowed: \", \', \\, \n, \r, \xNN, \uNNNN, where \xNN gives a raw byte
  value that is copied directly into an 8-bit string value, and \uNNNN
  gives a UTF-16 code unit that is converted to UTF-8 before being copied
  into an 8-bit string value. \x00 and \u0000 are disallowed because they
  would cause C++ code handling such strings to misbehave.
<pref-attrs>  = ("," <pref-attr>)*      // in default pref files
              = <empty>                 // in user pref files
<pref-attr>   = "sticky" | "locked"     // default pref files only

Default Config

In release builds these are all put into omni.ja.

User Config

Related Docs

Restrictions

It can be defined using only user_pref().

User pref file syntax is slightly more restrictive than default pref file syntax. In user pref files user_pref definitions are allowed but pref and sticky_pref definitions are not, and attributes (such as locked) are not allowed.

File Path

prefs.js, user.js is located in the profile directory.

about:config

It is written to prefs.js in a way that can be set by the GUI.

prefs.js

Related Docs

Basics It exists in the profile directory, and is used to store settings that are changed from defaults or when users added new settings.

In general, Do NOT edit prefs.js directly.

user.js

Related Docs

Restrictions

A user.js file can make certain preference settings more or less "permanent" in a specific profile.

Once an entry for a preference setting exists in the user.js file, any change you make to that setting in the options and preference dialogs or via about:config will be lost when you restart your firefox because the user.js entry will override it.

You'll have to first delete or edit the user.js file to remove the entries before the preferences can be changed in the application.

Example

// user.js
user_pref("browser.cache.disk.enable", false);                      // Bool
user_pref("layout.css.prefers-color-scheme.content-override", 3);   // Int
user_pref("general.smoothScroll.currentVelocityWeighting", "0.12"); // String

Auto Config

Related Docs

Basics Customizations that cannot be done with add-on and User Custom CSS, such as adding browser UI elements directly or changing default behavior, must use Auto Config.

How to

pref("general.config.filename", "config.js"); // alternative to "firefox.cfg", for using highlight
pref("general.config.obscure_value", 0);

Example

pref("general.config.filename", "config.js"); // alternative to "firefox.cfg", for using highlight
pref("general.config.obscure_value", 0);

Using with User Custom CSS

Related Docs

Restrictions

Please refer to Doc: Restrictions.md's @support.

Example

Test each case by turning on/off the following settings.

  • userChrome.navBar.red
  • userChrome.navBar.margin
/* userChrome.css */

/* 1. If config is true */
@supports -moz-bool-pref("userChrome.navBar.red") {
  #nav-bar {
    background-color: red !important;
  }
}

/* 2. When any one of the config is true */
@supports -moz-bool-pref("userChrome.navBar.red") or -moz-bool-pref("userChrome.navBar.margin") {
  #nav-bar {
    background-color: red !important;
    margin-block: 20px;
  }
}

/* 3. Multiple configs must all be satisfied */
@supports -moz-bool-pref("userChrome.navBar.red") and -moz-bool-pref("userChrome.navBar.margin") {
  #nav-bar {
    background-color: red !important;
    margin-block: 20px;
  }
}

/* 4. 3's Other version */
@supports -moz-bool-pref("userChrome.navBar.red") {
  @supports -moz-bool-pref("userChrome.navBar.margin") {
    #nav-bar {
      background-color: red !important;
      margin-block: 20px;
    }
  }
}

/* 5. If not exist or false */
@supports not -moz-bool-pref("userChrome.navBar.red") {
  #nav-bar {
    background-color: blue !important;
  }
}

Sync

Related Docs

How to

Firefox Sync allows you to choose the types of data to sync across all devices.

Choose sync data

The following options are required to sync custom configs.

  • services.sync.prefs.dangerously_allow_arbitrary to true

Then, subsequently any pref can be pushed there by creating a remote with prefix.

  • services.sync.prefs.sync.

Example

// user.js
user_pref("services.sync.prefs.dangerously_allow_arbitrary", true); // Must need

// Sync UI
user_pref("services.sync.prefs.sync.browser.uiCustomization.state", true);
user_pref("services.sync.prefs.sync.browser.uidensity", true);