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    _two_ 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] 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 template below,
  54    you should see a greeting and an inspection of VimFx’s public API.
  55
  56 Any time you make changes to any of your add-on files you need to restart
  57 Firefox to make the changes take effect.
  58
  59 Now you might want to read about the [public API] or look at the [Custom
  60 Commands] wiki page.
  61
  62 [install.rdf]: #installrdf
  63 [bootstrap.js]: #bootstrapjs
  64 [profile directory]: https://support.mozilla.org/en-US/kb/profiles-where-firefox-stores-user-data
  65 [proxy files]: https://developer.mozilla.org/en-US/Add-ons/Setting_up_extension_development_environment#Firefox_extension_proxy_file
  66 [browser console]: https://developer.mozilla.org/en-US/docs/Tools/Browser_Console
  67 [Custom Commands]: https://github.com/akhodakivskiy/VimFx/wiki/Custom-Commands
  68
  69
  70 ## install.rdf
  71
  72 This file tells Firefox that this is an add-on and provides some information
  73 about it. You’ll probably look at this once and not touch it again.
  74
  75 Here is a boilerplate that you can copy without changing anything (unless you
  76 feel like it):
  77
  78 ```rdf
  79 <?xml version="1.0" encoding="utf-8"?>
  80 <RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  81      xmlns:em="http://www.mozilla.org/2004/em-rdf#">
  82   <Description about="urn:mozilla:install-manifest">
  83
  84     <!-- Edit from here ... -->
  85     <em:name>VimFx-custom</em:name>
  86     <em:id>VimFx-custom@vimfx.org</em:id>
  87     <em:version>1</em:version>
  88     <!-- ... to here (if you feel like it). -->
  89
  90     <em:bootstrap>true</em:bootstrap>
  91     <em:multiprocessCompatible>true</em:multiprocessCompatible>
  92     <em:type>2</em:type>
  93     <em:targetApplication>
  94       <Description>
  95         <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
  96         <em:minVersion>38</em:minVersion>
  97         <em:maxVersion>*</em:maxVersion>
  98       </Description>
  99     </em:targetApplication>
 100   </Description>
 101 </RDF>
 102 ```
 103
 104 You might also want to read the [install.rdf documentation].
 105
 106 [install.rdf documentation]: https://developer.mozilla.org/en-US/Add-ons/Install_Manifests
 107
 108
 109 ## bootstrap.js
 110
 111 This is the actual config file, written in JavaScript.
 112
 113 Here is a boilerplate that you can copy as is:
 114
 115 ```js
 116 function startup() {
 117   let {classes: Cc, interfaces: Ci, utils: Cu} = Components
 118   Cu.import('resource://gre/modules/Services.jsm')
 119   Cu.import('resource://gre/modules/devtools/Console.jsm')
 120   let apiPref = 'extensions.VimFx.api_url'
 121   let apiUrl = Services.prefs.getComplexValue(apiPref, Ci.nsISupportsString).data
 122   Cu.import(apiUrl, {}).getAPI(vimfx => {
 123
 124     // Do things with the `vimfx` object between this line
 125     console.log('Hello, world! This is vimfx:', vimfx)
 126     // and this line.
 127
 128   })
 129 }
 130 function shutdown() {}
 131 function install() {}
 132 function uninstall() {}
 133 ```