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 be configured using a text file—called a _config file._ This should be
  10 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#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 [API]. Don’t worry, creating such an add-on is
  33 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 [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 If you add custom commands, remember to [add shortcuts to
  50 them][custom-command-shortcuts]!
  51
  52 Example:
  53
  54 ```js
  55 vimfx.set('hint_chars', 'abcdefghijklmnopqrstuvwxyz')
  56 vimfx.set('custom.mode.normal.zoom_in', 'zi')
  57 ```
  58
  59 [custom-command-shortcuts]: api.md#user-content-custom-command-shortcuts
  60
  61
  62 ## frame.js
  63
  64 If you add custom commands which access web page content, put their “frame
  65 script code” in this file.
  66
  67 This file is also where usage of the [frame script API] goes.
  68
  69 [frame script API]: api.md#frame-script-api
  70
  71 Here’s a typical pattern used in custom commands that communicate with a frame
  72 script:
  73
  74 ```js
  75 // config.js
  76 let {messageManager} = vim.window.gBrowser.selectedBrowser
  77 let callback = ({data: {selection}}) => {
  78   messageManager.removeMessageListener('VimFx-config:selection', callback)
  79   console.log('Currently selected text:', selection)
  80 }
  81 messageManager.addMessageListener('VimFx-config:selection', callback)
  82 messageManager.sendAsyncMessage('VimFx-config:getSelection', {exampleValue: 1337})
  83 ```
  84
  85 And here’s some accompanying frame script code:
  86
  87 ```js
  88 // frame.js
  89 addMessageListener('VimFx-config:getSelection', ({data: {exampleValue}}) => {
  90   console.log('exampleValue should be 5:', exampleValue)
  91   let selection = content.getSelection().toString()
  92   sendAsyncMessage('VimFx-config:selection', {selection})
  93 })
  94 ```