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 [custom commands]: api.md#vimfxaddcommandoptions-fn
  21 [special options]: options.md#special-options
  22 [overrides]: api.md#vimfxaddoptionoverridesrules-and-vimfxaddkeyoverridesrules
  23 [hint-matcher]: api.md#vimfxhintmatcher
  24 [Share your config file]: https://github.com/akhodakivskiy/VimFx/wiki/Share-your-config-file
  25
  26
  27 ## Technical notes
  28
  29 The config file is written in JavaScript and is actually a regular Firefox
  30 add-on, that makes use of VimFx’s [public API].
  31
  32 [public API]: api.md
  33
  34
  35 ## Setup
  36
  37 1. Create a directory for your config file to live in. Actually, there will be
  38    _three_ files that will live in it.
  39
  40 2. Create an [install.rdf] file in your directory. Inside that file there is an
  41    extension ID; take note of it.
  42
  43 3. Create a [bootstrap.js] and a [vimfx.js] file in your directory.
  44
  45 4. Find the `extensions/` directory in your [profile directory].
  46
  47 5. In the extensions directory, do one of the following:
  48
  49    - Move your config file directory into it, renamed as the extension ID.
  50
  51    - Create a plain text file named as the extension ID with the absolute path
  52      to your config file directory inside it. You might want to read the
  53      documentation about such [proxy files].
  54
  55    - Create a symlink named as the extension ID pointing to your config file
  56      directory.
  57
  58 6. Restart Firefox.
  59
  60 7. Open the [browser console]. If you copied the [bootstrap.js] and [vimfx.js]
  61    templates below, you should see a greeting and an inspection of VimFx’s
  62    public API.
  63
  64 Any time you make changes to any of your add-on files you need to restart
  65 Firefox to make the changes take effect.
  66
  67 Now you might want to read about the [public API] or look at the [Custom
  68 Commands][custom-commands-wiki] wiki page.
  69
  70 [install.rdf]: #installrdf
  71 [bootstrap.js]: #bootstrapjs
  72 [vimfx.js]: #vimfxjs
  73 [profile directory]: https://support.mozilla.org/en-US/kb/profiles-where-firefox-stores-user-data
  74 [proxy files]: https://developer.mozilla.org/en-US/Add-ons/Setting_up_extension_development_environment#Firefox_extension_proxy_file
  75 [browser console]: https://developer.mozilla.org/en-US/docs/Tools/Browser_Console
  76 [custom-commands-wiki]: https://github.com/akhodakivskiy/VimFx/wiki/Custom-Commands
  77
  78
  79 ## install.rdf
  80
  81 This file tells Firefox that this is an add-on and provides some information
  82 about it. You’ll probably look at this once and not touch it again.
  83
  84 Here is a boilerplate that you can copy without changing anything (unless you
  85 feel like it):
  86
  87 ```rdf
  88 <?xml version="1.0" encoding="utf-8"?>
  89 <RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  90      xmlns:em="http://www.mozilla.org/2004/em-rdf#">
  91   <Description about="urn:mozilla:install-manifest">
  92
  93     <!-- Edit from here ... -->
  94     <em:name>VimFx-custom</em:name>
  95     <em:id>VimFx-custom@vimfx.org</em:id>
  96     <em:version>1</em:version>
  97     <!-- ... to here (if you feel like it). -->
  98
  99     <em:bootstrap>true</em:bootstrap>
 100     <em:multiprocessCompatible>true</em:multiprocessCompatible>
 101     <em:type>2</em:type>
 102     <em:targetApplication>
 103       <Description>
 104         <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
 105         <em:minVersion>38</em:minVersion>
 106         <em:maxVersion>*</em:maxVersion>
 107       </Description>
 108     </em:targetApplication>
 109   </Description>
 110 </RDF>
 111 ```
 112
 113 You might also want to read the [install.rdf documentation].
 114
 115 [install.rdf documentation]: https://developer.mozilla.org/en-US/Add-ons/Install_Manifests
 116
 117
 118 ## bootstrap.js
 119
 120 This file starts up your add-on. Just like [install.rdf], you’ll probably look
 121 at this once and not touch it again.
 122
 123 Here is a boilerplate that you can copy as is. All it does is loading VimFx’s
 124 public API, as well as some very commonly used Firefox APIs, and passing those
 125 to [vimfx.js].
 126
 127 ```js
 128 let {classes: Cc, interfaces: Ci, utils: Cu} = Components
 129 function startup() {
 130   Cu.import('resource://gre/modules/Services.jsm')
 131   Cu.import('resource://gre/modules/devtools/Console.jsm')
 132   let apiPref = 'extensions.VimFx.api_url'
 133   let apiUrl = Services.prefs.getComplexValue(apiPref, Ci.nsISupportsString).data
 134   Cu.import(apiUrl, {}).getAPI(vimfx => {
 135     let path = __SCRIPT_URI_SPEC__.replace('bootstrap.js', 'vimfx.js')
 136     let scope = {Cc, Ci, Cu, vimfx}
 137     Services.scriptloader.loadSubScript(path, scope, 'UTF-8')
 138   })
 139 }
 140 function shutdown() {}
 141 function install() {}
 142 function uninstall() {}
 143 ```
 144
 145
 146 ## vimfx.js
 147
 148 This is the actual config file, written in JavaScript.
 149
 150 ```js
 151 console.log('Hello, world! This is vimfx:', vimfx)
 152 ```
 153
 154
 155 ## Frame script API and custom commands that access web page content
 156
 157 If you plan to use the [frame script API], or to add custom commands that need
 158 to access web page content, you have to add two more files and make an
 159 adjustment to bootstrap.js.
 160
 161 [frame script API]: api.md#frame-script-api
 162
 163 ### bootstrap.js adjustment
 164
 165 In bootstrap.js there is one function called `startup` and one called
 166 `shutdown`. At the end of the `startup` function, add the following:
 167
 168 ```js
 169 Cc['@mozilla.org/globalmessagemanager;1']
 170   .getService(Ci.nsIMessageListenerManager)
 171   .loadFrameScript('chrome://vimfx-custom/content/frame.js', true)
 172 ```
 173
 174 Inside the `shutdown` function, add the following:
 175
 176 ```js
 177 Cc['@mozilla.org/globalmessagemanager;1']
 178   .getService(Ci.nsIMessageListenerManager)
 179   .removeDelayedFrameScript('chrome://vimfx-custom/content/frame.js')
 180 ```
 181
 182 That will load a so called “frame script,” named [frame.js] in our case, and
 183 unload it when your add-on shuts down.
 184
 185 [frame.js]: #framejs
 186
 187 ### chrome.manifest
 188
 189 In order for Firefox to be able to find [frame.js], you need to add a file
 190 called `chrome.manifest` with the following contents:
 191
 192 ```
 193 content vimfx-custom ./
 194 ```
 195
 196 [frame.js]: #framejs
 197
 198 ### frame.js
 199
 200 Finally you of course need to add the file frame.js itself. Add any code that
 201 needs access web page content inside this file.
 202
 203 ### Example
 204
 205 Here’s a typical pattern used in custom commands that communicate with a frame
 206 script:
 207
 208 ```js
 209 let {messageManager} = vim.window.gBrowser.selectedBrowser
 210 let callback = ({data: {selection}}) => {
 211   messageManager.removeMessageListener('VimFx-custom:selection', callback)
 212   console.log('Currently selected text:', selection)
 213 }
 214 messageManager.addMessageListener('VimFx-custom:selection', callback)
 215 messageManager.sendAsyncMessage('VimFx-custom:getSelection', {exampleValue: 1337})
 216 ```
 217
 218 And here’s some accompaning frame script code:
 219
 220 ```js
 221 addMessageListener('VimFx-custom:getSelection', ({data: {exampleValue}}) => {
 222   console.log('exampleValue should be 5:', exampleValue)
 223   let selection = content.getSelection().toString()
 224   sendAsyncMessage('VimFx-custom:selection', {selection})
 225 })
 226 ```