2 This is part of the VimFx documentation.
3 Copyright Simon Lydell 2015.
4 See the file README.md for copying conditions.
9 VimFx can be configured using a configuration file. This should be done by users
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.
17 [special options]: options.md#special-options
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].
30 1. Create a directory for your config file to live in. Actually, there will be
31 _three_ files that will live in it.
33 2. Create an [install.rdf] file in your directory. Inside that file there is an
34 extension ID; take note of it.
36 3. Create a [bootstrap.js] and a [vimfx.js] file in your directory.
38 4. Find the `extensions/` directory in your [profile directory].
40 5. In the extensions directory, do one of the following:
42 - Move your config file directory into it, renamed as the extension ID.
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].
48 - Create a symlink named as the extension ID pointing to your config file
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
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.
60 Now you might want to read about the [public API] or look at the [Custom
63 [install.rdf]: #installrdf
64 [bootstrap.js]: #bootstrapjs
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
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.
77 Here is a boilerplate that you can copy without changing anything (unless you
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">
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). -->
92 <em:bootstrap>true</em:bootstrap>
93 <em:multiprocessCompatible>true</em:multiprocessCompatible>
95 <em:targetApplication>
97 <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
98 <em:minVersion>38</em:minVersion>
99 <em:maxVersion>*</em:maxVersion>
101 </em:targetApplication>
106 You might also want to read the [install.rdf documentation].
108 [install.rdf documentation]: https://developer.mozilla.org/en-US/Add-ons/Install_Manifests
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.
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
121 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')
133 function shutdown() {}
134 function install() {}
135 function uninstall() {}
141 This is the actual config file, written in JavaScript.
144 console.log('Hello, world! This is vimfx:', vimfx)
148 ## Custom commands that access web page content
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.
153 ### bootstrap.js adjustment
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:
159 Cc['@mozilla.org/globalmessagemanager;1']
160 .getService(Ci.nsIMessageListenerManager)
161 .loadFrameScript('chrome://vimfx-custom/content/frame.js', true)
164 Inside the `shutdown` function, add the following:
167 Cc['@mozilla.org/globalmessagemanager;1']
168 .getService(Ci.nsIMessageListenerManager)
169 .removeDelayedFrameScript('chrome://vimfx-custom/content/frame.js')
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.
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:
183 content vimfx-custom ./
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.
195 Here’s a typical pattern used in custom commands that communicate with a frame
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)
204 messageManager.addMessageListener('VimFx-custom:selection', callback)
205 messageManager.sendAsyncMessage('VimFx-custom:getSelection', {exampleValue: 1337})
208 And here’s some accompaning frame script code:
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})