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.
  16
  17 Look at the [Share your config file] wiki page for inspiration.
  18
  19 You get far just by copying and pasting.
  20
  21 [special options]: options.md#special-options
  22 [Share your config file]: https://github.com/akhodakivskiy/VimFx/wiki/Share-your-config-file
  23
  24
  25 ## Setup
  26
  27 The config file is written in JavaScript and is actually a regular Firefox
  28 add-on, that makes use of VimFx’s [public API]. Don’t worry, creating such an
  29 add-on is a lot easier than it might sound.
  30
  31 **[VimFx Config template – Download and instructions][config-template]**
  32
  33 Follow the above link to get started. Basically, download a few files and put
  34 them in a place where Firefox can find them.
  35
  36 [public API]: api.md
  37 [config-template]: https://github.com/lydell/VimFx-config/
  38
  39
  40 ## config.js
  41
  42 This is the actual config file, written in JavaScript. It is in this file you
  43 add custom commands and set options, or whatever you’d like to do.
  44
  45 Example:
  46
  47 ```js
  48 vimfx.set('hint_chars', 'abcdefghijklmnopqrstuvwxyz')
  49 ```
  50
  51
  52 ## frame.js
  53
  54 If you add custom commands that accesses web page content, put their "frame
  55 script code" in this file.
  56
  57 Here’s a typical pattern used in custom commands that communicate with a frame
  58 script:
  59
  60 ```js
  61 // config.js
  62 let {messageManager} = vim.window.gBrowser.selectedBrowser
  63 let callback = ({data: {selection}}) => {
  64   messageManager.removeMessageListener('VimFx-custom:selection', callback)
  65   console.log('Currently selected text:', selection)
  66 }
  67 messageManager.addMessageListener('VimFx-custom:selection', callback)
  68 messageManager.sendAsyncMessage('VimFx-custom:getSelection', {exampleValue: 1337})
  69 ```
  70
  71 And here’s some accompaning frame script code:
  72
  73 ```js
  74 // frame.js
  75 addMessageListener('VimFx-custom:getSelection', ({data: {exampleValue}}) => {
  76   console.log('exampleValue should be 5:', exampleValue)
  77   let selection = content.getSelection().toString()
  78   sendAsyncMessage('VimFx-custom:selection', {selection})
  79 })
  80 ```