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