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 to the path of your directory. (That’s
  48    an [advanced option].)
  49    Examples:
  50
  51    - GNU/Linux: `file:///home/you/.config/vimfx` or `file:///home/you/.vimfx`.
  52    - Windows: `file:///c:/Users/you/vimfx` – note that `\` should be replaced
  53      with `/`!
  54
  55    If you’re unsure, drag and drop `config.js` from your file manager into
  56    Firefox, and copy the path from the location bar. (Remember to remove
  57    `/config.js` from the end of it, though!)
  58
  59 4. Run the `zr` command in VimFx. That needs to be done any time
  60    `config_file_directory` is changed, or the contents of `config.js` or
  61    `frame.js` are changed. This tells VimFx to reload the config file. If
  62    everything went well, a [notification] should appear telling you that the
  63    config file was successfully reloaded.
  64
  65 [`config_file_directory`]: options.md#config_file_directory
  66 [advanced option]: options.md#advanced-options
  67 [notification]: notifications.md
  68
  69
  70 ## Tips
  71
  72 If you make errors in `config.js` or `frame.js` they will appear in the [browser
  73 console].
  74
  75 Remember to press `zr` after you’ve edited `config.js` or `frame.js` to reload
  76 them. A [notification] will appear telling you if there was any trouble
  77 reloading or not.
  78
  79 Use `console.log(...)` to inspect things. For example, try putting
  80 `console.log('This is vimfx:', vimfx)` in `config.js`. Then, open the [browser
  81 console]. There you should see an entry with the message “This is vimfx:” as
  82 well as an interactive inspection of the `vimfx` object.
  83
  84 [browser console]: https://developer.mozilla.org/en-US/docs/Tools/Browser_Console
  85 [notification]: notifications.md
  86
  87
  88 ## Scope
  89
  90 Both `config.js` and `frame.js` have access to the following variables:
  91
  92 - `vimfx`: VimFx’s [`config.js` API] or [`frame.js` API]. You’ll probably only
  93   work with this object and not much else.
  94 - [`console`]: Let’s you print things to the [browser console]. Great for
  95   simple debugging.
  96 - [`Components`]: This object is available to all add-ons, and is the main
  97   gateway to all of Firefox’s internals. This lets advanced users do basically
  98   anything, as if they had created a full regular Firefox add-on.
  99 - [`Services`]: Shortcuts to some `Components` stuff.
 100
 101 `frame.js` also has access to the entire standard Firefox [frame script
 102 environment], which might be interesting to advanced users.
 103
 104 [`config.js` API]: api.md#configjs-api
 105 [`frame.js` API]: api.md#framejs-api
 106 [`console`]: https://developer.mozilla.org/en-US/docs/Web/API/console
 107 [`Components`]: https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Language_Bindings/Components_object
 108 [`Services`]: https://developer.mozilla.org/en-US/docs/Mozilla/JavaScript_code_modules/Services.jsm
 109 [frame script environment]: https://developer.mozilla.org/en-US/Firefox/Multiprocess_Firefox/Frame_script_environment
 110 [browser console]: https://developer.mozilla.org/en-US/docs/Tools/Browser_Console
 111
 112
 113 ## config.js
 114
 115 This is the actual config file, where you’ll do most things. It is in this file
 116 you add custom commands and set options, or whatever you’d like to do.
 117
 118 Example code:
 119
 120 ```js
 121 vimfx.set('hint_chars', 'abcdefghijklmnopqrstuvwxyz')
 122 vimfx.set('custom.mode.normal.zoom_in', 'zi')
 123 ```
 124
 125 If you add custom commands, remember to [add shortcuts to
 126 them][custom-command-shortcuts]!
 127
 128 [custom-command-shortcuts]: api.md#user-content-custom-command-shortcuts
 129
 130
 131 ## frame.js
 132
 133 If you add custom commands which access web page content, put their “frame
 134 script code” in this file.
 135
 136 Typically, all you do in `frame.js` is listening for messages from `config.js`
 137 and reponding to those messages with some data from the current web page, which
 138 only `frame.js` has access to. The [`vimfx.send(...)`] documentation has an
 139 example of this.
 140
 141 Note: Even if you don’t need `frame.js` right now, the file still must exist if
 142 `config.js` exists. Simply leave it blank.
 143
 144 [`vimfx.send(...)`]: api.md#vimfxsendvim-message-data--null-callback--null
 145
 146
 147 ## When is the config file executed?
 148
 149 - Every time VimFx starts up. In other words, when Firefox starts up and when
 150   you update VimFx (or disable and then enable it).
 151 - Every time you use the `zr` command to reload the config file.
 152
 153 “Executing the config file” means running `config.js` once and `frame.js` for
 154 each open tab. `frame.js` also runs every time you open a new tab.
 155
 156 (See also [the `shutdown` event].)
 157
 158 [the `shutdown` event]: api.md#the-shutdown-event