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://developer.mozilla.org/en-US/docs/Tools/Browser_Console
  85 [web console]: https://developer.mozilla.org/en-US/docs/Tools/Web_Console
  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 [`config.js` API]: api.md#configjs-api
 114 [`frame.js` API]: api.md#framejs-api
 115 [`console`]: https://developer.mozilla.org/en-US/docs/Web/API/console
 116 [`Components`]: https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Language_Bindings/Components_object
 117 [`Services`]: https://developer.mozilla.org/en-US/docs/Mozilla/JavaScript_code_modules/Services.jsm
 118 [frame script environment]: https://developer.mozilla.org/en-US/Firefox/Multiprocess_Firefox/Frame_script_environment
 119 [`Window`]: https://developer.mozilla.org/en-US/docs/Web/API/Window
 120 [browser console]: https://developer.mozilla.org/en-US/docs/Tools/Browser_Console
 121 [web console]: https://developer.mozilla.org/en-US/docs/Tools/Web_Console
 122
 123
 124 ## config.js
 125
 126 This is the actual config file, where you’ll do most things. It is in this file
 127 you add custom commands and set options, or whatever you’d like to do. However,
 128 [due to how Firefox is designed][e10s], it can _not_ access web page content.
 129 That’s why `frame.js` exists.
 130
 131 Example code:
 132
 133 ```js
 134 vimfx.set('hints.chars', 'abcdefghijklmnopqrstuvw xyz')
 135 vimfx.set('custom.mode.normal.zoom_in', 'zi')
 136 ```
 137
 138 If you add custom commands, remember to [add shortcuts to
 139 them][custom-command-shortcuts]!
 140
 141 Tip: If you already have made customizations in VimFx’s options page in the
 142 Add-ons Manager, you can use the “Export all” button there to copy all options
 143 as JSON. Paste it in your config file and either edit it, or iterate over it:
 144
 145 ```js
 146 let options = {"hints.chars": "1234567 89"} // Pasted exported options.
 147 Object.entries(options).forEach(([option, value]) => vimfx.set(option, value))
 148 ```
 149
 150 [custom-command-shortcuts]: api.md#user-content-custom-command-shortcuts
 151 [e10s]: https://developer.mozilla.org/en-US/Firefox/Multiprocess_Firefox
 152
 153
 154 ## frame.js
 155
 156 [Due to how Firefox is designed][e10s], only `frame.js` can access web page
 157 content. On the other hand, it cannot acccess many things that `config.js` can.
 158 Instead of simply doing everything on `config.js`, you need to send messages
 159 between `config.js` and `frame.js`.
 160
 161 Typically, all you do in `frame.js` is listening for messages from `config.js`
 162 and reponding to those messages with some data from the current web page, which
 163 only `frame.js` has access to. **The [`vimfx.send(...)`] documentation has an
 164 example of this.**
 165
 166 Even if you don’t need `frame.js` right now, the file still must exist if
 167 `config.js` exists. Simply leave it blank.
 168
 169 (`config.js` actually _can_ access web page content in some circumstances.
 170 However, that’s a legacy Firefox feature that can stop working at any time, and
 171 can even slow Firefox down! Don’t use such methods if you come across them.)
 172
 173 [`vimfx.send(...)`]: api.md#vimfxsendvim-message-data--null-callback--null
 174 [e10s]: https://developer.mozilla.org/en-US/Firefox/Multiprocess_Firefox
 175
 176
 177 ## When is the config file executed?
 178
 179 - Every time VimFx starts up. In other words, when Firefox starts up and when
 180   you update VimFx (or disable and then enable it).
 181 - Every time you use the `gC` command to reload the config file.
 182
 183 “Executing the config file” means running `config.js` once and `frame.js` for
 184 each open tab. `frame.js` also runs every time you open a new tab.
 185
 186 (See also [the `shutdown` event].)
 187
 188 [the `shutdown` event]: api.md#the-shutdown-event
 189
 190
 191 ## On Process Sandboxing
 192
 193 Electrolysis (e10s) introduced a process sandbox; a security feature limiting
 194 the impact of exploits in a content process. With the release of Firefox
 195 Quantum (57) the sandbox was tightened to disallow file system reads, which
 196 requires `frame.js` and other files accessed from a content process to be
 197 whitelisted. Mozilla provides a pref,
 198 `security.sandbox.content.read_path_whitelist`, that accepts a comma-separated
 199 list of paths. If a path ends with a path separator (i.e. `/` or `\`), the
 200 whole directory will become whitelisted. This pref is unavailable on OS X,
 201 where you instead get two [undocumented prefs],
 202 `security.sandbox.content.mac.testing_read_path1` and
 203 `security.sandbox.content.mac.testing_read_path2`, each accepting one directory
 204 path to whitelist.
 205
 206 If you want to read other files from the file system from `frame.js`, place
 207 them inside the whitelisted directory or add their paths to the
 208 `read_path_whitelist`. Analogously, a `write_path_whitelist` exists on non-OSX
 209 systems; OS X users may be able to write to the `extensions` and `chrome`
 210 subdirectories inside the profile directory instead.
 211
 212 Weakening the sandbox by setting `security.sandbox.content.level` to 2 is not
 213 recommended, as this will open up a [potentially devastating security hole].
 214
 215 [undocumented prefs]: https://hg.mozilla.org/mozilla-central/file/c31591e0b66f277398bee74da03c49e8f8a0ede0/dom/ipc/ContentChild.cpp#l1701
 216 [potentially devesatating security hole]: https://bugzilla.mozilla.org/show_bug.cgi?id=1221148#c30