From 8348ae78d901b737984949aef90c1396e2ef90b3 Mon Sep 17 00:00:00 2001 From: Simon Lydell Date: Tue, 27 Sep 2016 18:22:07 +0200 Subject: [PATCH] Improve config file documentation Refs. #815. --- documentation/api.md | 13 ++++--- documentation/config-file.md | 71 ++++++++++++++++++++++++------------ 2 files changed, 56 insertions(+), 28 deletions(-) diff --git a/documentation/api.md b/documentation/api.md index 33ed81b..5bd9fac 100644 --- a/documentation/api.md +++ b/documentation/api.md @@ -186,10 +186,12 @@ vimfx.addKeyOverrides( ### `vimfx.send(vim, message, data = null, callback = null)` Send `message` (a string) to the instance of `frame.js` in the tab managed by -[`vim`][vim object], and pass it `data`. If provided, `callback` must be a -function that takes a single argument, which is the data that `frame.js` -responds with. `frame.js` uses its [`vimfx.listen(...)`] method to listen for -(and optionally respond to) `message`. +[`vim`][vim object], and pass it `data`. `frame.js` uses its +[`vimfx.listen(...)`] method to listen for (and optionally respond to) +`message`. + +If provided, `callback` must be a function. That function will receive a single +argument: The data that `frame.js` responds with. Here is an example: @@ -205,6 +207,7 @@ vimfx.send(vim, 'getSelection', {example: 5}, selection => { // frame.js vimfx.listen('getSelection', ({example}, callback) => { console.log('`example` should be 5:', example) + // `content` is basically the same as the `window` of the page. let selection = content.getSelection().toString() callback(selection) }) @@ -212,7 +215,7 @@ vimfx.listen('getSelection', ({example}, callback) => { What if you want to do it the other way around: Send a message _from_ `frame.js` and listen for it in `config.js`? That’s not the common use case, so VimFx does -not provide convenience functions for it. Yes, `vimfx.send(...)`, and +not provide convenience functions for it. `vimfx.send(...)`, and `vimfx.listen(...)` in `frame.js`, are just light wrappers around the standard Firefox [Message Manager] to make it easier to create custom commands that ask `frame.js` for information about the current web page (as in the above example). diff --git a/documentation/config-file.md b/documentation/config-file.md index 401f5e1..34500ed 100644 --- a/documentation/config-file.md +++ b/documentation/config-file.md @@ -10,7 +10,7 @@ VimFx can optionally be configured using a text file—called a _config file._ This should be done by users who: - prefer to configure things using text files. -- would like to add [custom commands]. +- would like to add [custom commands] \(and [share custom commands]!). - would like to set [special options]. - would like to make [site-specific customizations][overrides]. - would like to customize [which elements do and don’t get hints][hint-matcher]. @@ -23,18 +23,19 @@ You get far just by copying and pasting. [special options]: options.md#special-options [overrides]: api.md#vimfxaddoptionoverrides-and-vimfxaddkeyoverrides [hint-matcher]: api.md#vimfxsethintmatcherhintmatcher +[share custom commands]: https://github.com/akhodakivskiy/VimFx/wiki/Custom-Commands [Share your config file]: https://github.com/akhodakivskiy/VimFx/wiki/Share-your-config-file ## Getting started -VimFx requires you to provide either none or _two_ config files: `config.js` and +VimFx requires you to provide either none or _two_ files: `config.js` and `frame.js`. Even though they are technically two, it’s easier to just say “the config file,” (in singular) and think of `config.js` is the _actual_ config file and `frame.js` as an implementation detail. Both of these files are written in JavaScript and are explained in more detail in the upcoming sections. -Follow these steps to get started with your config file: +Follow these steps to get started: 1. Create a directory, anywhere on your hard drive. Examples: @@ -44,17 +45,18 @@ Follow these steps to get started with your config file: 2. Create two empty plain text files in your directory, called `config.js` and `frame.js`. -3. Set the [`config_file_directory`] option (that’s an [advanced option]) to the - path of the directory you created above. It can be either absolute, such as - `/home/you/.config/vimfx` or `C:\Users\you\vimfx`, or start with a `~`, which - is a shortcut to your home directory, such as `~/.config/vimfx` or `~\vimfx`. +3. Go to [about:config] and set the [`config_file_directory`] option to the path + of the directory you created above. The path can be either absolute, such as + `/home/you/.config/vimfx` or `C:\Users\you\vimfx`, or start with a `~` (which + is a shortcut to your home directory) such as `~/.config/vimfx` or `~\vimfx`. -4. Run the `gC` command in VimFx. That needs to be done any time - `config_file_directory` is changed, or the contents of `config.js` or - `frame.js` are changed. This tells VimFx to reload the config file. If - everything went well, a [notification] should appear telling you that the - config file was successfully reloaded. +4. Run the `gC` command in VimFx. That needs to be done any time you change + `config_file_directory`, or edit `config.js` or `frame.js`. This tells VimFx + to reload the config file. If everything went well, a [notification] should + appear (in the bottom-right corner of the window) telling you that the config + file was successfully reloaded. +[about:config]: http://kb.mozillazine.org/About:config [`config_file_directory`]: options.md#config_file_directory [advanced option]: options.md#advanced-options [notification]: notifications.md @@ -67,14 +69,20 @@ console]. Remember to press `gC` after you’ve edited `config.js` or `frame.js` to reload them. A [notification] will appear telling you if there was any trouble -reloading or not. +reloading or not. If there was, more information will be available in the +[browser console]. Use `console.log(...)` to inspect things. For example, try putting `console.log('This is vimfx:', vimfx)` in `config.js`. Then, open the [browser console]. There you should see an entry with the message “This is vimfx:” as well as an interactive inspection of the `vimfx` object. +Note: The [**browser** console][browser console] (default Firefox shortcut: +``) is not the same as the [_web_ console][web console] (default Firefox +shortcut: ``). It’s easy to mix them up as a beginner! + [browser console]: https://developer.mozilla.org/en-US/docs/Tools/Browser_Console +[web console]: https://developer.mozilla.org/en-US/docs/Tools/Web_Console [notification]: notifications.md @@ -84,8 +92,8 @@ Both `config.js` and `frame.js` have access to the following variables: - `vimfx`: VimFx’s [`config.js` API] or [`frame.js` API]. You’ll probably only work with this object and not much else. -- [`console`]: Let’s you print things to the [browser console]. Great for - simple debugging. +- [`console`]: Let’s you print things to the [browser console]. Great for simple + debugging. - `__dirname`: The full path to the config file directory, in a format that Firefox likes to work with. Useful if you want to import other files relative to the config file. @@ -93,6 +101,11 @@ Both `config.js` and `frame.js` have access to the following variables: gateway to all of Firefox’s internals. This lets advanced users do basically anything, as if they had created a full regular Firefox add-on. - [`Services`]: Shortcuts to some `Components` stuff. +- `content`: Available in `frame.js` only. If you’ve ever done web development, + this is basically the same as `window` in regular web pages, or `window` in + the [web console]. This object lets you access web page content, for example + by using `content.document.querySelector('a')`. See [`Window`] for more + information. `frame.js` also has access to the entire standard Firefox [frame script environment], which might be interesting to advanced users. @@ -103,18 +116,22 @@ environment], which might be interesting to advanced users. [`Components`]: https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Language_Bindings/Components_object [`Services`]: https://developer.mozilla.org/en-US/docs/Mozilla/JavaScript_code_modules/Services.jsm [frame script environment]: https://developer.mozilla.org/en-US/Firefox/Multiprocess_Firefox/Frame_script_environment +[`Window`]: https://developer.mozilla.org/en-US/docs/Web/API/Window [browser console]: https://developer.mozilla.org/en-US/docs/Tools/Browser_Console +[web console]: https://developer.mozilla.org/en-US/docs/Tools/Web_Console ## config.js This is the actual config file, where you’ll do most things. It is in this file -you add custom commands and set options, or whatever you’d like to do. +you add custom commands and set options, or whatever you’d like to do. However, +[due to how Firefox is designed][e10s], it can _not_ access web page content. +That’s why `frame.js` exists. Example code: ```js -vimfx.set('hints.chars', 'abcdefghijklmnopqrstuvwxyz') +vimfx.set('hints.chars', 'abcdefghijklmnopqrstuvw xyz') vimfx.set('custom.mode.normal.zoom_in', 'zi') ``` @@ -123,7 +140,7 @@ them][custom-command-shortcuts]! Tip: If you already have made customizations in VimFx’s options page in the Add-ons Manager, you can use the “Export all” button there to copy all options -as JSON. Paste it in your config file and either edit it, or iterate of it: +as JSON. Paste it in your config file and either edit it, or iterate over it: ```js let options = {"hints.chars": "1234567 89"} // Pasted exported options. @@ -131,22 +148,30 @@ Object.entries(options).forEach(([option, value]) => vimfx.set(option, value)) ``` [custom-command-shortcuts]: api.md#user-content-custom-command-shortcuts +[e10s]: https://developer.mozilla.org/en-US/Firefox/Multiprocess_Firefox ## frame.js -If you add custom commands which access web page content, put their “frame -script code” in this file. +[Due to how Firefox is designed][e10s], only `frame.js` can access web page +content. On the other hand, it cannot acccess many things that `config.js` can. +Instead of simply doing everything on `config.js`, you need to send messages +between `config.js` and `frame.js`. Typically, all you do in `frame.js` is listening for messages from `config.js` and reponding to those messages with some data from the current web page, which -only `frame.js` has access to. The [`vimfx.send(...)`] documentation has an -example of this. +only `frame.js` has access to. **The [`vimfx.send(...)`] documentation has an +example of this.** -Note: Even if you don’t need `frame.js` right now, the file still must exist if +Even if you don’t need `frame.js` right now, the file still must exist if `config.js` exists. Simply leave it blank. +(`config.js` actually _can_ access web page content in some circumstances. +However, that’s a legacy Firefox feature that can stop working at any time, and +can even slow Firefox down! Don’t use such methods if you come across them.) + [`vimfx.send(...)`]: api.md#vimfxsendvim-message-data--null-callback--null +[e10s]: https://developer.mozilla.org/en-US/Firefox/Multiprocess_Firefox ## When is the config file executed? -- 2.39.3