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 `zr` 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 `zr` 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 - [`Components`]: This object is available to all add-ons, and is the main
  90   gateway to all of Firefox’s internals. This lets advanced users do basically
  91   anything, as if they had created a full regular Firefox add-on.
  92 - [`Services`]: Shortcuts to some `Components` stuff.
  93
  94 `frame.js` also has access to the entire standard Firefox [frame script
  95 environment], which might be interesting to advanced users.
  96
  97 [`config.js` API]: api.md#configjs-api
  98 [`frame.js` API]: api.md#framejs-api
  99 [`console`]: https://developer.mozilla.org/en-US/docs/Web/API/console
 100 [`Components`]: https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Language_Bindings/Components_object
 101 [`Services`]: https://developer.mozilla.org/en-US/docs/Mozilla/JavaScript_code_modules/Services.jsm
 102 [frame script environment]: https://developer.mozilla.org/en-US/Firefox/Multiprocess_Firefox/Frame_script_environment
 103 [browser console]: https://developer.mozilla.org/en-US/docs/Tools/Browser_Console
 104
 105
 106 ## config.js
 107
 108 This is the actual config file, where you’ll do most things. It is in this file
 109 you add custom commands and set options, or whatever you’d like to do.
 110
 111 Example code:
 112
 113 ```js
 114 vimfx.set('hint_chars', 'abcdefghijklmnopqrstuvwxyz')
 115 vimfx.set('custom.mode.normal.zoom_in', 'zi')
 116 ```
 117
 118 If you add custom commands, remember to [add shortcuts to
 119 them][custom-command-shortcuts]!
 120
 121 [custom-command-shortcuts]: api.md#user-content-custom-command-shortcuts
 122
 123
 124 ## frame.js
 125
 126 If you add custom commands which access web page content, put their “frame
 127 script code” in this file.
 128
 129 Typically, all you do in `frame.js` is listening for messages from `config.js`
 130 and reponding to those messages with some data from the current web page, which
 131 only `frame.js` has access to. The [`vimfx.send(...)`] documentation has an
 132 example of this.
 133
 134 Note: Even if you don’t need `frame.js` right now, the file still must exist if
 135 `config.js` exists. Simply leave it blank.
 136
 137 [`vimfx.send(...)`]: api.md#vimfxsendvim-message-data--null-callback--null
 138
 139
 140 ## When is the config file executed?
 141
 142 - Every time VimFx starts up. In other words, when Firefox starts up and when
 143   you update VimFx (or disable and then enable it).
 144 - Every time you use the `zr` command to reload the config file.
 145
 146 “Executing the config file” means running `config.js` once and `frame.js` for
 147 each open tab. `frame.js` also runs every time you open a new tab.
 148
 149 (See also [the `shutdown` event].)
 150
 151 [the `shutdown` event]: api.md#the-shutdown-event