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