documentation/config-file.md

   1 <!--
   2 This is part of the VimFx documentation.
   3 Copyright Simon Lydell 2015, 2016.
   4 See the file README.md for copying conditions.
   5 -->
   6
   7 # Config file
   8
   9 VimFx can optionally be configured using a text file—called a _config file._
  10 This should be done by users who:
  11
  12 - prefer to configure things using text files.
  13 - would like to add [custom commands].
  14 - would like to set [special options].
  15 - would like to make [site-specific customizations][overrides].
  16 - would like to customize [which elements do and don’t get hints][hint-matcher].
  17
  18 Look at the [Share your config file] wiki page for inspiration.
  19
  20 You get far just by copying and pasting.
  21
  22 [custom commands]: api.md#vimfxaddcommandoptions-fn
  23 [special options]: options.md#special-options
  24 [overrides]: api.md#vimfxaddoptionoverrides-and-vimfxaddkeyoverrides
  25 [hint-matcher]: api.md#vimfxsethintmatcherhintmatcher
  26 [Share your config file]: https://github.com/akhodakivskiy/VimFx/wiki/Share-your-config-file
  27
  28
  29 ## Getting started
  30
  31 VimFx requires you to provide either none or _two_ config files: `config.js` and
  32 `frame.js`. Even though they are technically two, it’s easier to just say “the
  33 config file,” (in singular) and think of `config.js` is the _actual_ config file
  34 and `frame.js` as an implementation detail. Both of these files are written in
  35 JavaScript and are explained in more detail in the upcoming sections.
  36
  37 Follow these steps to get started with your config file:
  38
  39 1. Create a directory, anywhere on your hard drive. Examples:
  40
  41    - GNU/Linux: `~/.config/vimfx` or `~/.vimfx`.
  42    - Windows: `c:\Users\you\vimfx`.
  43
  44 2. Create two empty plain text files in your directory, called `config.js` and
  45    `frame.js`.
  46
  47 3. Set the [`config_file_directory`] pref (that’s an [advanced option]) to the
  48    path of the directory you created above. It can be either absolute, such as
  49    `/home/you/.config/vimfx` or `C:\Users\you\vimfx`, or start with a `~`, which
  50    is a shortcut to your home directory, such as `~/.config/vimfx` or `~\vimfx`.
  51
  52 4. Run the `gC` command in VimFx. That needs to be done any time
  53    `config_file_directory` is changed, or the contents of `config.js` or
  54    `frame.js` are changed. This tells VimFx to reload the config file. If
  55    everything went well, a [notification] should appear telling you that the
  56    config file was successfully reloaded.
  57
  58 [`config_file_directory`]: options.md#config_file_directory
  59 [advanced option]: options.md#advanced-options
  60 [notification]: notifications.md
  61
  62
  63 ## Tips
  64
  65 If you make errors in `config.js` or `frame.js` they will appear in the [browser
  66 console].
  67
  68 Remember to press `gC` after you’ve edited `config.js` or `frame.js` to reload
  69 them. A [notification] will appear telling you if there was any trouble
  70 reloading or not.
  71
  72 Use `console.log(...)` to inspect things. For example, try putting
  73 `console.log('This is vimfx:', vimfx)` in `config.js`. Then, open the [browser
  74 console]. There you should see an entry with the message “This is vimfx:” as
  75 well as an interactive inspection of the `vimfx` object.
  76
  77 [browser console]: https://developer.mozilla.org/en-US/docs/Tools/Browser_Console
  78 [notification]: notifications.md
  79
  80
  81 ## Scope
  82
  83 Both `config.js` and `frame.js` have access to the following variables:
  84
  85 - `vimfx`: VimFx’s [`config.js` API] or [`frame.js` API]. You’ll probably only
  86   work with this object and not much else.
  87 - [`console`]: Let’s you print things to the [browser console]. Great for
  88   simple debugging.
  89 - `__dirname`: The full path to the config file directory, in a format that
  90   Firefox likes to work with. Useful if you want to import other files relative
  91   to the config file.
  92 - [`Components`]: This object is available to all add-ons, and is the main
  93   gateway to all of Firefox’s internals. This lets advanced users do basically
  94   anything, as if they had created a full regular Firefox add-on.
  95 - [`Services`]: Shortcuts to some `Components` stuff.
  96
  97 `frame.js` also has access to the entire standard Firefox [frame script
  98 environment], which might be interesting to advanced users.
  99
 100 [`config.js` API]: api.md#configjs-api
 101 [`frame.js` API]: api.md#framejs-api
 102 [`console`]: https://developer.mozilla.org/en-US/docs/Web/API/console
 103 [`Components`]: https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Language_Bindings/Components_object
 104 [`Services`]: https://developer.mozilla.org/en-US/docs/Mozilla/JavaScript_code_modules/Services.jsm
 105 [frame script environment]: https://developer.mozilla.org/en-US/Firefox/Multiprocess_Firefox/Frame_script_environment
 106 [browser console]: https://developer.mozilla.org/en-US/docs/Tools/Browser_Console
 107
 108
 109 ## config.js
 110
 111 This is the actual config file, where you’ll do most things. It is in this file
 112 you add custom commands and set options, or whatever you’d like to do.
 113
 114 Example code:
 115
 116 ```js
 117 vimfx.set('hint_chars', 'abcdefghijklmnopqrstuvwxyz')
 118 vimfx.set('custom.mode.normal.zoom_in', 'zi')
 119 ```
 120
 121 If you add custom commands, remember to [add shortcuts to
 122 them][custom-command-shortcuts]!
 123
 124 Tip: If you already have made customizations in VimFx’s settings page in the
 125 Add-ons Manager, you can use the “Export all” button there to copy all prefs as
 126 JSON. Paste it in your config file and either edit it, or iterate of it:
 127
 128 ```js
 129 let prefs = {"hint_chars": "1234567 89"} // Pasted exported prefs.
 130 Object.entries(prefs).forEach(([pref, value]) => vimfx.set(pref, value))
 131 ```
 132
 133 [custom-command-shortcuts]: api.md#user-content-custom-command-shortcuts
 134
 135
 136 ## frame.js
 137
 138 If you add custom commands which access web page content, put their “frame
 139 script code” in this file.
 140
 141 Typically, all you do in `frame.js` is listening for messages from `config.js`
 142 and reponding to those messages with some data from the current web page, which
 143 only `frame.js` has access to. The [`vimfx.send(...)`] documentation has an
 144 example of this.
 145
 146 Note: Even if you don’t need `frame.js` right now, the file still must exist if
 147 `config.js` exists. Simply leave it blank.
 148
 149 [`vimfx.send(...)`]: api.md#vimfxsendvim-message-data--null-callback--null
 150
 151
 152 ## When is the config file executed?
 153
 154 - Every time VimFx starts up. In other words, when Firefox starts up and when
 155   you update VimFx (or disable and then enable it).
 156 - Every time you use the `gC` command to reload the config file.
 157
 158 “Executing the config file” means running `config.js` once and `frame.js` for
 159 each open tab. `frame.js` also runs every time you open a new tab.
 160
 161 (See also [the `shutdown` event].)
 162
 163 [the `shutdown` event]: api.md#the-shutdown-event