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. Run the `gC` command in VimFx. That needs to be done any time you change
  48    `config_file_directory`, or edit `config.js` or `frame.js`. This tells VimFx
  49    to reload the config file. If everything went well, a [notification] should
  50    appear (in the bottom-right corner of the window) telling you that the config
  51    file was successfully reloaded.
  52
  53 [about:config]: http://kb.mozillazine.org/About:config
  54 [`config_file_directory`]: options.md#config_file_directory
  55 [advanced option]: options.md#advanced-options
  56 [notification]: notifications.md
  57
  58
  59 ## Tips
  60
  61 If you make errors in `config.js` or `frame.js` they will appear in the [browser
  62 console].
  63
  64 Remember to press `gC` after you’ve edited `config.js` or `frame.js` to reload
  65 them. A [notification] will appear telling you if there was any trouble
  66 reloading or not. If there was, more information will be available in the
  67 [browser console].
  68
  69 Use `console.log(...)` to inspect things. For example, try putting
  70 `console.log('This is vimfx:', vimfx)` in `config.js`. Then, open the [browser
  71 console]. There you should see an entry with the message “This is vimfx:” as
  72 well as an interactive inspection of the `vimfx` object.
  73
  74 Note: The [**browser** console][browser console] (default Firefox shortcut:
  75 `<c-J>`) is not the same as the [_web_ console][web console] (default Firefox
  76 shortcut: `<c-K>`). It’s easy to mix them up as a beginner!
  77
  78 [browser console]: https://developer.mozilla.org/en-US/docs/Tools/Browser_Console
  79 [web console]: https://developer.mozilla.org/en-US/docs/Tools/Web_Console
  80 [notification]: notifications.md
  81
  82
  83 ## Scope
  84
  85 Both `config.js` and `frame.js` have access to the following variables:
  86
  87 - `vimfx`: VimFx’s [`config.js` API] or [`frame.js` API]. You’ll probably only
  88   work with this object and not much else.
  89 - [`console`]: Let’s you print things to the [browser console]. Great for simple
  90   debugging.
  91 - `__dirname`: The full path to the config file directory, in a format that
  92   Firefox likes to work with. Useful if you want to import other files relative
  93   to the config file.
  94 - [`Components`]: This object is available to all add-ons, and is the main
  95   gateway to all of Firefox’s internals. This lets advanced users do basically
  96   anything, as if they had created a full regular Firefox add-on.
  97 - [`Services`]: Shortcuts to some `Components` stuff.
  98 - `content`: Available in `frame.js` only. If you’ve ever done web development,
  99   this is basically the same as `window` in regular web pages, or `window` in
 100   the [web console]. This object lets you access web page content, for example
 101   by using `content.document.querySelector('a')`. See [`Window`] for more
 102   information.
 103
 104 `frame.js` also has access to the entire standard Firefox [frame script
 105 environment], which might be interesting to advanced users.
 106
 107 [`config.js` API]: api.md#configjs-api
 108 [`frame.js` API]: api.md#framejs-api
 109 [`console`]: https://developer.mozilla.org/en-US/docs/Web/API/console
 110 [`Components`]: https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Language_Bindings/Components_object
 111 [`Services`]: https://developer.mozilla.org/en-US/docs/Mozilla/JavaScript_code_modules/Services.jsm
 112 [frame script environment]: https://developer.mozilla.org/en-US/Firefox/Multiprocess_Firefox/Frame_script_environment
 113 [`Window`]: https://developer.mozilla.org/en-US/docs/Web/API/Window
 114 [browser console]: https://developer.mozilla.org/en-US/docs/Tools/Browser_Console
 115 [web console]: https://developer.mozilla.org/en-US/docs/Tools/Web_Console
 116
 117
 118 ## config.js
 119
 120 This is the actual config file, where you’ll do most things. It is in this file
 121 you add custom commands and set options, or whatever you’d like to do. However,
 122 [due to how Firefox is designed][e10s], it can _not_ access web page content.
 123 That’s why `frame.js` exists.
 124
 125 Example code:
 126
 127 ```js
 128 vimfx.set('hints.chars', 'abcdefghijklmnopqrstuvw xyz')
 129 vimfx.set('custom.mode.normal.zoom_in', 'zi')
 130 ```
 131
 132 If you add custom commands, remember to [add shortcuts to
 133 them][custom-command-shortcuts]!
 134
 135 Tip: If you already have made customizations in VimFx’s options page in the
 136 Add-ons Manager, you can use the “Export all” button there to copy all options
 137 as JSON. Paste it in your config file and either edit it, or iterate over it:
 138
 139 ```js
 140 let options = {"hints.chars": "1234567 89"} // Pasted exported options.
 141 Object.entries(options).forEach(([option, value]) => vimfx.set(option, value))
 142 ```
 143
 144 [custom-command-shortcuts]: api.md#user-content-custom-command-shortcuts
 145 [e10s]: https://developer.mozilla.org/en-US/Firefox/Multiprocess_Firefox
 146
 147
 148 ## frame.js
 149
 150 [Due to how Firefox is designed][e10s], only `frame.js` can access web page
 151 content. On the other hand, it cannot acccess many things that `config.js` can.
 152 Instead of simply doing everything on `config.js`, you need to send messages
 153 between `config.js` and `frame.js`.
 154
 155 Typically, all you do in `frame.js` is listening for messages from `config.js`
 156 and reponding to those messages with some data from the current web page, which
 157 only `frame.js` has access to. **The [`vimfx.send(...)`] documentation has an
 158 example of this.**
 159
 160 Even if you don’t need `frame.js` right now, the file still must exist if
 161 `config.js` exists. Simply leave it blank.
 162
 163 (`config.js` actually _can_ access web page content in some circumstances.
 164 However, that’s a legacy Firefox feature that can stop working at any time, and
 165 can even slow Firefox down! Don’t use such methods if you come across them.)
 166
 167 [`vimfx.send(...)`]: api.md#vimfxsendvim-message-data--null-callback--null
 168 [e10s]: https://developer.mozilla.org/en-US/Firefox/Multiprocess_Firefox
 169
 170
 171 ## When is the config file executed?
 172
 173 - Every time VimFx starts up. In other words, when Firefox starts up and when
 174   you update VimFx (or disable and then enable it).
 175 - Every time you use the `gC` command to reload the config file.
 176
 177 “Executing the config file” means running `config.js` once and `frame.js` for
 178 each open tab. `frame.js` also runs every time you open a new tab.
 179
 180 (See also [the `shutdown` event].)
 181
 182 [the `shutdown` event]: api.md#the-shutdown-event