Permalink
Browse files

clearer pageFn vs fn

  • Loading branch information...
mikob
mikob committed Oct 25, 2018
1 parent f78693a commit f60c8f4f7a98715f4080f26d09daf641523a9273
Showing with 17 additions and 12 deletions.
  1. +1 −1 docs/.vuepress/dist
  2. +16 −11 docs/api-reference/command.md
Submodule dist updated from 29deb7 to 006f79
@@ -6,17 +6,22 @@ Also see [`ILocalizedCommand`](/api-reference/command.md#ilocalizedcommand).

Each command has the following properties:

Member | Type | Description
-------|------------|-------------
name | `string` | Friendly-name of the command (not necessarily the words used to call it).
match| `string | string[] | `[`IDynamicMatch`](/api-reference/command.md#idynamicmatch) | The word(s) the user can say to execute this command. Use "#" in the string as an ordinal place holder. Use "*" as a wildcard placeholder. Lastly, a function [`IDynamicMatch`](/api-reference/command.md#idynamicmatch) can be used for the most advanced cases.
description | `string` | _(optional)_ Detailed description visible in the options page.
global | `boolean` | _(default: false)_ let the command match on any page (not restricted by the `match` of the Plugin)
pageFn | `(transcript: string, ...matchOutput: any) => Promise<any>` | _(optional)_ An async function to run on the page when the command is called. Special matches (`*` and `#`) will be arguments after the transcript string argument, and will come in the order they are specified in the match property. There will be a number argument if the match string accepts an ordinal (eg. has a `#`) in it, or a string argument if the match string accepts a wildcard (eg. has a `*` in it). Use `fn` if you need the function to run in the context of the extension rather than the page.
delay | `number | number[]` | _(optional)_ How long to wait for additional input for before executing this command. <br><br> For example with the Google command the user can have a long search term like "search how to boost my wifi signal" in order to prevent the command from executing the search as soon as it hears "search how" instead of the full phrase, we put a delay so that it waits for X ms since the last voice input. <br><br> Use an array with indices that correspond to the different match strings if you should have different delays based on the match string.
nice | [`INiceCommand`](/api-reference/command.md#inicecommand) | _(optional)_ See [`INiceCommand`](/api-reference/command.md#inicecommand).
fn | `(transcript: string, ...matchOutput: any) => any` | _(optional)_ An async function that runs in the Chrome extension context when the command is called. First arg is the transcript that matched, rest of arguments are what's returned from the match command. `pageFn` is preferred, which runs in the context of the active tab page.
test | `() => void` | _(optional but recommended)_ Selenium unit test for this command.
|Member | Type | Description|
|-------|------------|-------------|
|name | `string` | Friendly-name of the command (not necessarily the words used to call it).|
|match| `string | string[] | `[`IDynamicMatch`](/api-reference/command.md#idynamicmatch) | The word(s) the user can say to execute this command. Use "#" in the string as an ordinal place holder. Use "*" as a wildcard placeholder. Lastly, a function [`IDynamicMatch`](/api-reference/command.md#idynamicmatch) can be used for the most advanced cases.
|description | `string` | _(optional)_ Detailed description visible in the options page.|
|global | `boolean` | _(default: false)_ let the command match on any page (not restricted by the `match` of the Plugin)|
pageFn | `(transcript: string, ...matchOutput: any) => Promise<any>` | _(optional)_ An async function to run on the page when the command is called. Special matches (`*` and `#`) will be arguments after the transcript string argument, and will come in the order they are specified in the match property. There will be a number argument if the match string accepts an ordinal (eg. has a `#`) in it, or a string argument if the match string accepts a wildcard (eg. has a `*` in it).<br><br> Also see [fn vs. pageFn](/api-reference/command.md#fn-vs-pagefn).
|delay | `number | number[]` | _(optional)_ How long to wait for additional input for before executing this command. <br><br> For example with the Google command the user can have a long search term like "search how to boost my wifi signal" in order to prevent the command from executing the search as soon as it hears "search how" instead of the full phrase, we put a delay so that it waits for X ms since the last voice input. <br><br> Use an array with indices that correspond to the different match strings if you should have different delays based on the match string.|
|nice | [`INiceCommand`](/api-reference/command.md#inicecommand) | _(optional)_ See [`INiceCommand`](/api-reference/command.md#inicecommand).|
|fn | `(transcript: string, ...matchOutput: any) => any` | _(optional)_ An async function that runs in the Chrome extension context when the command is called. First arg is the transcript that matched, rest of arguments are what's returned from the match command. <br><br> Also see [fn vs. pageFn](/api-reference/command.md#fn-vs-pagefn).|
|test | `() => void` | _(optional but recommended)_ Selenium unit test for this command.|

### `fn` vs. `pageFn`
::: tip NOTE
`pageFn` runs in the context of the page so it has access to the DOM, but doesn't have access to Chrome extension APIs like `chrome.tabs`. `fn` on the other hand runs in the (sandboxed) context of the Chrome extension; it doesn't have access to the page or it's DOM but it does have access to the Chrome extension APIs. `pageFn` is preferred unless you need access to extension APIs.
:::


## IDynamicMatch

0 comments on commit f60c8f4

Please sign in to comment.