documentation/config-file.md

   1 # Config file
   2
   3 VimFx can optionally be configured using a text file—called a _config file._
   4 This should be done by users who:
   5
   6 - prefer to configure things using text files.
   7 - would like to add [custom commands] \(and [share custom commands]!).
   8 - would like to set [special options].
   9 - would like to make [site-specific customizations][overrides].
  10 - would like to customize [which elements do and don’t get hints][hint-matcher].
  11
  12 Look at the [Share your config file] wiki page for inspiration.
  13
  14 You get far just by copying and pasting.
  15
  16 [custom commands]: api.md#vimfxaddcommandoptions-fn
  17 [special options]: options.md#special-options
  18 [overrides]: api.md#vimfxaddoptionoverrides-and-vimfxaddkeyoverrides
  19 [hint-matcher]: api.md#vimfxsethintmatcherhintmatcher
  20 [share custom commands]: https://github.com/akhodakivskiy/VimFx/wiki/Custom-Commands
  21 [Share your config file]: https://github.com/akhodakivskiy/VimFx/wiki/Share-your-config-file
  22
  23
  24 ## Getting started
  25
  26 VimFx requires you to provide either none or _two_ files: `config.js` and
  27 `frame.js`. Even though they are technically two, it’s easier to just say “the
  28 config file,” (in singular) and think of `config.js` is the _actual_ config file
  29 and `frame.js` as an implementation detail. Both of these files are written in
  30 JavaScript and are explained in more detail in the upcoming sections.
  31
  32 Follow these steps to get started:
  33
  34 1. Create a directory, anywhere on your hard drive. Examples:
  35
  36    - GNU/Linux: `~/.config/vimfx` or `~/.vimfx`.
  37    - Windows: `c:\Users\you\vimfx`.
  38
  39 2. Create two empty plain text files in your directory, called `config.js` and
  40    `frame.js`.
  41
  42 3. Go to [about:config] and set the [`config_file_directory`] option to the path
  43    of the directory you created above. The path can be either absolute, such as
  44    `/home/you/.config/vimfx` or `C:\Users\you\vimfx`, or start with a `~` (which
  45    is a shortcut to your home directory) such as `~/.config/vimfx` or `~\vimfx`.
  46
  47 4. If you are running Firefox 57+, whitelist the `config_file_directory` by
  48    setting `security.sandbox.content.read_path_whitelist` (Linux and Windows) or
  49    `security.sandbox.content.mac.testing_read_path1` (OS X) to the absolute path
  50    of the config directory (`~` not supported) ending on `/` (or `\`). You may
  51    have to restart the browser after modifying these prefs.
  52
  53 5. Run the `gC` command in VimFx. That needs to be done any time you change
  54    `config_file_directory`, or edit `config.js` or `frame.js`. This tells VimFx
  55    to reload the config file. If everything went well, a [notification] should
  56    appear (in the bottom-right corner of the window) telling you that the config
  57    file was successfully reloaded.
  58
  59 [about:config]: http://kb.mozillazine.org/About:config
  60 [`config_file_directory`]: options.md#config_file_directory
  61 [advanced option]: options.md#advanced-options
  62 [notification]: notifications.md
  63
  64
  65 ## Tips
  66
  67 If you make errors in `config.js` or `frame.js` they will appear in the [browser
  68 console].
  69
  70 Remember to press `gC` after you’ve edited `config.js` or `frame.js` to reload
  71 them. A [notification] will appear telling you if there was any trouble
  72 reloading or not. If there was, more information will be available in the
  73 [browser console].
  74
  75 Use `console.log(...)` to inspect things. For example, try putting
  76 `console.log('This is vimfx:', vimfx)` in `config.js`. Then, open the [browser
  77 console]. There you should see an entry with the message “This is vimfx:” as
  78 well as an interactive inspection of the `vimfx` object.
  79
  80 Note: The [**browser** console][browser console] (default Firefox shortcut:
  81 `<c-J>`) is not the same as the [_web_ console][web console] (default Firefox
  82 shortcut: `<c-K>`). It’s easy to mix them up as a beginner!
  83
  84 [browser console]: https://firefox-source-docs.mozilla.org/devtools-user/browser_console/index.html
  85 [web console]: https://firefox-source-docs.mozilla.org/devtools-user/web_console/index.html
  86 [notification]: notifications.md
  87
  88
  89 ## Scope
  90
  91 Both `config.js` and `frame.js` have access to the following variables:
  92
  93 - `vimfx`: VimFx’s [`config.js` API] or [`frame.js` API]. You’ll probably only
  94   work with this object and not much else.
  95 - [`console`]: Let’s you print things to the [browser console]. Great for simple
  96   debugging.
  97 - `__dirname`: The full path to the config file directory, in a format that
  98   Firefox likes to work with. Useful if you want to import other files relative
  99   to the config file.
 100 - [`Components`]: This object is available to all add-ons, and is the main
 101   gateway to all of Firefox’s internals. This lets advanced users do basically
 102   anything, as if they had created a full regular Firefox add-on.
 103 - [`Services`]: Shortcuts to some `Components` stuff.
 104 - `content`: Available in `frame.js` only. If you’ve ever done web development,
 105   this is basically the same as `window` in regular web pages, or `window` in
 106   the [web console]. This object lets you access web page content, for example
 107   by using `content.document.querySelector('a')`. See [`Window`] for more
 108   information.
 109
 110 `frame.js` also has access to the entire standard Firefox [frame script
 111 environment], which might be interesting to advanced users.
 112
 113 <!-- NOTE: docs for Components, Services, frame script environment did not survive the MDN purge -->
 114 [`config.js` API]: api.md#configjs-api
 115 [`frame.js` API]: api.md#framejs-api
 116 [`console`]: https://developer.mozilla.org/en-US/docs/Web/API/console
 117 [`Components`]: https://web.archive.org/web/20210614111450/https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Language_Bindings/Components_object
 118 [`Services`]: https://web.archive.org/web/20210415055941/https://developer.mozilla.org/en-US/docs/Mozilla/JavaScript_code_modules/Services.jsm
 119 [frame script environment]: https://web.archive.org/web/20201221164134/https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Multiprocess_Firefox/Frame_script_environment
 120 [`Window`]: https://developer.mozilla.org/en-US/docs/Web/API/Window
 121 [browser console]: https://firefox-source-docs.mozilla.org/devtools-user/browser_console/index.html
 122 [web console]: https://firefox-source-docs.mozilla.org/devtools-user/web_console/index.html
 123
 124
 125 ## config.js
 126
 127 This is the actual config file, where you’ll do most things. It is in this file
 128 you add custom commands and set options, or whatever you’d like to do. However,
 129 [due to how Firefox is designed][e10s], it can _not_ access web page content.
 130 That’s why `frame.js` exists.
 131
 132 Example code:
 133
 134 ```js
 135 vimfx.set('hints.chars', 'abcdefghijklmnopqrstuvw xyz')
 136 vimfx.set('custom.mode.normal.zoom_in', 'zi')
 137 ```
 138
 139 If you add custom commands, remember to [add shortcuts to
 140 them][custom-command-shortcuts]!
 141
 142 Tip: If you already have made customizations in VimFx’s options page in the
 143 Add-ons Manager, you can use the “Export all” button there to copy all options
 144 as JSON. Paste it in your config file and either edit it, or iterate over it:
 145
 146 ```js
 147 let options = {"hints.chars": "1234567 89"} // Pasted exported options.
 148 Object.entries(options).forEach(([option, value]) => vimfx.set(option, value))
 149 ```
 150
 151 [custom-command-shortcuts]: api.md#user-content-custom-command-shortcuts
 152 [e10s]: https://firefox-source-docs.mozilla.org/dom/ipc/process_model.html
 153
 154
 155 ## frame.js
 156
 157 [Due to how Firefox is designed][e10s], only `frame.js` can access web page
 158 content. On the other hand, it cannot acccess many things that `config.js` can.
 159 Instead of simply doing everything on `config.js`, you need to send messages
 160 between `config.js` and `frame.js`.
 161
 162 Typically, all you do in `frame.js` is listening for messages from `config.js`
 163 and reponding to those messages with some data from the current web page, which
 164 only `frame.js` has access to. **The [`vimfx.send(...)`] documentation has an
 165 example of this.**
 166
 167 Even if you don’t need `frame.js` right now, the file still must exist if
 168 `config.js` exists. Simply leave it blank.
 169
 170 (`config.js` actually _can_ access web page content in some circumstances.
 171 However, that’s a legacy Firefox feature that can stop working at any time, and
 172 can even slow Firefox down! Don’t use such methods if you come across them.)
 173
 174 [`vimfx.send(...)`]: api.md#vimfxsendvim-message-data--null-callback--null
 175 [e10s]: https://firefox-source-docs.mozilla.org/dom/ipc/process_model.html
 176
 177
 178 ## When is the config file executed?
 179
 180 - Every time VimFx starts up. In other words, when Firefox starts up and when
 181   you update VimFx (or disable and then enable it).
 182 - Every time you use the `gC` command to reload the config file.
 183
 184 “Executing the config file” means running `config.js` once and `frame.js` for
 185 each open tab. `frame.js` also runs every time you open a new tab.
 186
 187 (See also [the `shutdown` event].)
 188
 189 [the `shutdown` event]: api.md#the-shutdown-event
 190
 191
 192 ## On Process Sandboxing
 193
 194 Electrolysis (e10s) introduced a process sandbox; a security feature limiting
 195 the impact of exploits in a content process. With the release of Firefox
 196 Quantum (57) the sandbox was tightened to disallow file system reads, which
 197 requires `frame.js` and other files accessed from a content process to be
 198 whitelisted. Mozilla provides a pref,
 199 `security.sandbox.content.read_path_whitelist`, that accepts a comma-separated
 200 list of paths. If a path ends with a path separator (i.e. `/` or `\`), the
 201 whole directory will become whitelisted. This pref is unavailable on OS X,
 202 where you instead get two [undocumented prefs],
 203 `security.sandbox.content.mac.testing_read_path1` and
 204 `security.sandbox.content.mac.testing_read_path2`, each accepting one directory
 205 path to whitelist.
 206
 207 If you want to read other files from the file system from `frame.js`, place
 208 them inside the whitelisted directory or add their paths to the
 209 `read_path_whitelist`. Analogously, a `write_path_whitelist` exists on non-OSX
 210 systems; OS X users may be able to write to the `extensions` and `chrome`
 211 subdirectories inside the profile directory instead.
 212
 213 Weakening the sandbox by setting `security.sandbox.content.level` to 2 is not
 214 recommended, as this will open up a [potentially devastating security hole].
 215
 216 [undocumented prefs]: https://hg.mozilla.org/mozilla-central/file/c31591e0b66f277398bee74da03c49e8f8a0ede0/dom/ipc/ContentChild.cpp#l1701
 217 [potentially devastating security hole]: https://bugzilla.mozilla.org/show_bug.cgi?id=1221148#c30