LipSurf Plugin Developer DocumentationContexts
Contexts are groups of commands that can be combined to determine which commands are relevant or valid for the page's current state. By default, if a command does not have a context, it is in the PluginBase.constants.contexts.Normal context where most default commands live. LipSurf is always in one or more contexts.
Example use cases:
Allowing certain commands only in certain situations.
- e.g. When we're watching a Netflix show, we want play, pause etc. available. When we're browsing the Netflix catalogue, we don't want player commands, but we do want things like next page. To handle this, we could watch for URL changes, and if we're on a page to watch a show, we could use
prependContext('Player Controls')to add the context that the player controls are under.
NOTE
Because we used
prependContextthe default commands will still work, because the Normal context remains in the context list.- e.g. When we're watching a Netflix show, we want play, pause etc. available. When we're browsing the Netflix catalogue, we don't want player commands, but we do want things like next page. To handle this, we could watch for URL changes, and if we're on a page to watch a show, we could use
Limiting which commands are valid.
- e.g. In the "Dictation" context, we don't want youtube to take us to youtube.com, we want it to literally write "youtube" where we're composing our text. In this case we don't want the "Normal" context, so we would
enterContext(["Dictation"])to replace the current context with only "Dictation".
- e.g. In the "Dictation" context, we don't want youtube to take us to youtube.com, we want it to literally write "youtube" where we're composing our text. In this case we don't want the "Normal" context, so we would
Contexts are per-tab. So the user may be in a dictation mode in one tab, and normal mode in another.
WARNING
- Make sure to remove a context if it's specific to the plugin in the plugin's destroy function.
Context Order
Context order matters. If there are two search * commands, the one from the context earlier in the context list gets chosen.
Designating a Context
A context is "created" by designating:
- A command's
enterContextproperty - A plugin's
contextsproperty
Context can be manipulated programmatically using:
PluginBase.util.enterContextPluginBase.util.prependContextPluginBase.util.appendContextPluginBase.util.removeContextPluginBase.util.getContext
Commands Outside of Normal Mode
By default, a command is in the PluginBase.constants.contexts.Normal (default) context unless normal: false is specified or a context is specified that doesn't include PluginBase.constants.contexts.Normal.