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