Skip to content

Latest commit

 

History

History
266 lines (203 loc) · 10 KB

Preference.md

File metadata and controls

266 lines (203 loc) · 10 KB
Raw

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

.mjs(ES6 Module) is also used in FF v102 or above.

How to

  • <FIREFOX_DIR>/defaults/pref/autoconfig.js
pref("general.config.filename", "config.js"); // alternative to "firefox.cfg", for using highlight
pref("general.config.obscure_value", 0);
pref("general.config.sandbox_enabled", false); // Sandbox needs to be disabled in release and Beta versions
  • <FIREFOX_DIR>/config.js
// skip 1st line
try {
  const cmanifest = Cc['@mozilla.org/file/directory_service;1'].getService(Ci.nsIProperties).get('UChrm', Ci.nsIFile);
  cmanifest.append('utils');
  cmanifest.append('chrome.manifest');

  if(cmanifest.exists()){
    Components.manager.QueryInterface(Ci.nsIComponentRegistrar).autoRegister(cmanifest);
    ChromeUtils.import('chrome://userchromejs/content/boot.jsm');
  }

} catch(ex) {};

Example

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);

Related Source file