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

247 lines
9.2 KiB
Markdown

# Preference
<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
**Table of Contents**
- [Basics](#basics)
- [Default Config](#default-config)
- [User Config](#user-config)
* [about:config](#aboutconfig)
* [prefs.js](#prefsjs)
* [user.js](#userjs)
- [Auto Config](#auto-config)
- [Using with User Custom CSS](#using-with-user-custom-css)
- [Sync](#sync)
- [Related Source file](#related-source-file)
<!-- markdown-toc end -->
## Basics
**Related Docs**
- [Firefox Source Docs: libpref](https://firefox-source-docs.mozilla.org/modules/libpref/index.html)
**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)](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form) if you want to know about syntax.
```ebnf
<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
- [`modules/libpref/init/all.js`](https://github.com/mozilla/gecko-dev/blob/master/modules/libpref/init/all.js): all products
- [`browser/app/profile/firefox.js`](https://github.com/mozilla/gecko-dev/blob/master/browser/app/profile/firefox.js): only firefox deskstop
In release builds these are all put into [`omni.ja`](./Omni_ja.md).
## User Config
**Related Docs**
- [mozillaZine: Editing configuration](https://kb.mozillazine.org/Editing_configuration)
- [Support Mozilla: How to fix preferences that won't save](https://support.mozilla.org/en-US/kb/how-to-fix-preferences-wont-save)
- [Support Mozilla: Reset Firefox preferences to troubleshoot and fix problems](https://support.mozilla.org/en-US/kb/reset-preferences-fix-problems)
- [UDN: A brief guide to Mozilla preferences](https://udn.realityripple.com/docs/Mozilla/Preferences/A_brief_guide_to_Mozilla_preferences)
**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.
- [Support Mozilla: Configuration Editor for Firefox](https://support.mozilla.org/en-US/kb/about-config-editor-firefox)
### prefs.js
**Related Docs**
- [mozillaZine: Prefs.js file](https://kb.mozillazine.org/Prefs.js_file)
**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**
- [mozillaZine: User.js file](https://kb.mozillazine.org/User.js_file)
**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**
```javascript
// 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**
- [Support Mozilla: Customizing Firefox Using AutoConfig](https://support.mozilla.org/en-US/kb/customizing-firefox-using-autoconfig)
- [What is Autoconfig Startup Scripting (AKA userChrome.js)?](https://www.userchrome.org/what-is-userchrome-js.html)
- [UDN: Gecko Chrome](https://udn.realityripple.com/docs/Mozilla/Gecko/Chrome)
- [UDN: JavaScript code modules](https://udn.realityripple.com/docs/Mozilla/JavaScript_code_modules)
- [UDN: Limitations of chrome scripts](https://udn.realityripple.com/docs/Mozilla/Firefox/Multiprocess_Leftovers/Limitations_of_chrome_scripts)
**Basics**
Customizations that cannot be done with add-on and [`User Custom CSS`](./README.md#user-custom-css), such as adding browser UI elements directly or changing default behavior, must use `Auto Config`.
**How to**
```javascript
pref("general.config.filename", "config.js"); // alternative to "firefox.cfg", for using highlight
pref("general.config.obscure_value", 0);
```
**Example**
```javascript
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**
- [MDN: @supports](https://developer.mozilla.org/en-US/docs/Web/CSS/@supports)
- [UDN: `CSS -moz-bool-pref() @supports function`](https://udn.realityripple.com/docs/Mozilla/Gecko/Chrome/CSS/-moz-bool-pref)
**Restrictions**
Please refer to [Doc: Restrictions.md](./Restrictions.md#supports)'s `@support`.
**Example**
Test each case by turning on/off the following settings.
- `userChrome.navBar.red`
- `userChrome.navBar.margin`
```css
/* 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**
- [Support Mozilla: Sync custom preferences](https://support.mozilla.org/en-US/kb/sync-custom-preferences)
**How to**
Firefox Sync allows you to [choose the types of data](https://support.mozilla.org/en-US/kb/how-do-i-choose-what-information-sync-firefox) to sync across all devices.
![Choose sync data](https://user-images.githubusercontent.com/25581533/162106009-85f8efe6-c310-488b-9940-763b6e7dd271.png)
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**
```javascript
// 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
- https://github.com/mozilla/gecko-dev/blob/master/modules/libpref/parser/src/lib.rs
- https://github.com/mozilla/gecko-dev/blob/master/extensions/pref/autoconfig/src/prefcalls.js