documentation/config-file.md

   1 <!--
   2 This is part of the VimFx documentation.
   3 Copyright Simon Lydell 2015.
   4 See the file README.md for copying conditions.
   5 -->
   6
   7 # Config file
   8
   9 VimFx can be configured using a configuration file. This should be done by users
  10 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#vimfxaddoptionoverridesrules-and-vimfxaddkeyoverridesrules
  25 [hint-matcher]: api.md#vimfxhintmatcher
  26 [Share your config file]: https://github.com/akhodakivskiy/VimFx/wiki/Share-your-config-file
  27
  28
  29 ## Setup
  30
  31 The config file is written in JavaScript and is actually a regular Firefox
  32 add-on, that makes use of VimFx’s [public API]. Don’t worry, creating such an
  33 add-on is a lot easier than it might sound.
  34
  35 **[VimFx Config template – Download and instructions][config-template]**
  36
  37 Follow the above link to get started. Basically, download a few files and put
  38 them in a place where Firefox can find them.
  39
  40 [public API]: api.md
  41 [config-template]: https://github.com/lydell/VimFx-config/
  42
  43
  44 ## config.js
  45
  46 This is the actual config file, written in JavaScript. It is in this file you
  47 add custom commands and set options, or whatever you’d like to do.
  48
  49 Example:
  50
  51 ```js
  52 vimfx.set('hint_chars', 'abcdefghijklmnopqrstuvwxyz')
  53 ```
  54
  55
  56 ## frame.js
  57
  58 If you add custom commands that accesses web page content, put their "frame
  59 script code" in this file.
  60
  61 This file is also where usage of the [frame script API] goes.
  62
  63 [frame script API]: api.md#frame-script-api
  64
  65 Here’s a typical pattern used in custom commands that communicate with a frame
  66 script:
  67
  68 ```js
  69 // config.js
  70 let {messageManager} = vim.window.gBrowser.selectedBrowser
  71 let callback = ({data: {selection}}) => {
  72   messageManager.removeMessageListener('VimFx-config:selection', callback)
  73   console.log('Currently selected text:', selection)
  74 }
  75 messageManager.addMessageListener('VimFx-config:selection', callback)
  76 messageManager.sendAsyncMessage('VimFx-config:getSelection', {exampleValue: 1337})
  77 ```
  78
  79 And here’s some accompanying frame script code:
  80
  81 ```js
  82 // frame.js
  83 addMessageListener('VimFx-config:getSelection', ({data: {exampleValue}}) => {
  84   console.log('exampleValue should be 5:', exampleValue)
  85   let selection = content.getSelection().toString()
  86   sendAsyncMessage('VimFx-config:selection', {selection})
  87 })
  88 ```