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 function startup() {
 122   let {classes: Cc, interfaces: Ci, utils: Cu} = Components
 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 ```