Execution API

API definition for using Pluggable Electron in the renderer process

Managing the execution of Pluggable Electron activation and extension points is done in the renderer. The activation manager needs to be set up before the other features can be used in the renderer.

The activation and execution managers can be imported in the renderer process by requiring pluggable electron. E.g. import { extensionPoints, activationPoints } from "pluggable-electron"

To access the plugin manager from the renderer, the Plugin Manager must first be initialised in the main process, and facade must be initialised in the renderer. If nodeIntegration is set to true, the facade can be imported directly in the renderer, otherwise this needs to be imported in the preload script. Examples:

const useFacade = require("pluggable-electron/facade")
useFacade()

All of the items described below can be accessed by importing Pluggable Electron in the renderer except for the Facade. This requires a separate import as described above.

Classes

ExtensionPoint

Represents a point in the consumer's code that can be extended by a plugin. The plugin can register a callback or object to the extension point. When the extension point is triggered, the provided function will then be called or object will be returned.

Plugin

A slimmed down representation of a plugin for the renderer.

Objects

activationPoints : object

This object contains a register of plugin registrations to an activation points, and the means to work with them.

extensionPoints : object

This object contains a register of extension points and the means to work with them.

plugins : object

Helper functions to access the plugin management in the main process. Note that the facade needs to be imported separately as "pluggable-electron/facade" as described above. It is then available on the global window object as describe in the Electron documentation

Functions

setup(options) ⇒ void

Set the renderer options for Pluggable Electron. Should be called before any other Pluggable Electron function in the renderer

Typedefs

Extension : Object

An extension registered to an extension point

installOptions : Object.<string, any>

The pacote options used to install the plugin.

importer ⇒ module

Used to import a plugin entry point. Ensure your bundler does no try to resolve this import as the plugins are not known at build time.

ExtensionPoint

Represents a point in the consumer's code that can be extended by a plugin. The plugin can register a callback or object to the extension point. When the extension point is triggered, the provided function will then be called or object will be returned.

Kind: global class

• ExtensionPoint
  • .name : string
  • .register(name, response, [priority]) ⇒ void
  • .unregister(name) ⇒ void
  • .clear() ⇒ void
  • .get(name) ⇒ Object | Callback | undefined
  • .execute(input) ⇒ Array
  • .executeSerial(input) ⇒ Promise.<*>
  • .onRegister(name, callback)
  • .offRegister(name)

extensionPoint.name : string

Name of the extension point

Kind: instance property of ExtensionPoint

extensionPoint.register(name, response, [priority]) ⇒ void

Register new extension with this extension point. The registered response will be executed (if callback) or returned (if object) when the extension point is executed (see below).

Kind: instance method of ExtensionPoint

Param	Type	Default	Description
name	string		Unique name for the extension.
response	Object | Callback		Object to be returned or function to be called by the extension point.
[priority]	number	0	Order priority for execution used for executing in serial.

extensionPoint.unregister(name) ⇒ void

Remove an extension from the registry. It will no longer be part of the extension point execution.

Kind: instance method of ExtensionPoint

Param	Type	Description
name	RegExp	Matcher for the name of the extension to remove.

extensionPoint.clear() ⇒ void

Empty the registry of all extensions.

Kind: instance method of ExtensionPoint

extensionPoint.get(name) ⇒ Object | Callback | undefined

Get a specific extension registered with the extension point

Kind: instance method of ExtensionPoint
Returns: Object | Callback | undefined - The response of the extension. If this is a function the function is returned, not its response.

Param	Type	Description
name	string	Name of the extension to return

extensionPoint.execute(input) ⇒ Array

Execute (if callback) and return or just return (if object) the response for each extension registered to this extension point. Any asynchronous responses will be executed in parallel and the returned array will contain a promise for each of these responses.

Kind: instance method of ExtensionPoint
Returns: Array - List of responses from the extensions.

Param	Type	Description
input	*	Input to be provided as a parameter to each response if response is a callback.

extensionPoint.executeSerial(input) ⇒ Promise.<*>

Execute (if callback) and return the response, or push it to the array if the previous response is an array for each extension registered to this extension point in serial, feeding the result from the last response as input to the next.

Kind: instance method of ExtensionPoint
Returns: Promise.<*> - Result of the last extension that was called

Param	Type	Description
input	*	Input to be provided as a parameter to the 1st callback

extensionPoint.onRegister(name, callback)

Register a callback to be executed if the list of extensions changes.

Kind: instance method of ExtensionPoint

Param	Type	Description
name	string	Name of the listener needed if it is to be removed.
callback	function	The callback function to trigger on a change.

extensionPoint.offRegister(name)

Unregister a callback from the extension list changes.

Kind: instance method of ExtensionPoint

Param	Type	Description
name	string	The name of the listener to remove.

Plugin

A slimmed down representation of a plugin for the renderer.

Kind: global class

• Plugin
  • .name : string
  • .url : string
  • .activationPoints : Array.<string>
  • .active : boolean
  • .triggerExport(exp)

plugin.name : string

Name of the package.

Kind: instance property of Plugin

plugin.url : string

The electron url where this plugin is located.

Kind: instance property of Plugin

plugin.activationPoints : Array.<string>

List of activation points.

Kind: instance property of Plugin

plugin.active : boolean

Whether this plugin should be activated when its activation points are triggered.

Kind: instance property of Plugin

plugin.triggerExport(exp)

Trigger an exported callback on the plugin's main file.

Kind: instance method of Plugin

Param	Type	Description
exp	string	exported callback to trigger.

activationPoints : object

This object contains a register of plugin registrations to an activation points, and the means to work with them.

Kind: global namespace

• activationPoints : object
  • .register(plugin) ⇒ void
  • .trigger(activationPoint) ⇒ Promise.<Boolean>
  • .remove(plugin) ⇒ void
  • .clear() ⇒ void
  • .get() ⇒ Array.<Activation>

activationPoints.register(plugin) ⇒ void

Register a plugin with its activation points (as defined in its manifest).

Kind: static method of activationPoints

Param	Type	Description
plugin	Plugin	plugin object as provided by the main process.

activationPoints.trigger(activationPoint) ⇒ Promise.<Boolean>

Trigger all activations registered to the given activation point. See Plugin. This will call the function with the same name as the activation point on the path specified in the plugin.

Kind: static method of activationPoints
Returns: Promise.<Boolean> - Resolves to true when the activations are complete.

Param	Type	Description
activationPoint	string	Name of the activation to trigger

activationPoints.remove(plugin) ⇒ void

Remove a plugin from the activations register.

Kind: static method of activationPoints

Param	Type	Description
plugin	string	Name of the plugin to remove.

activationPoints.clear() ⇒ void

Remove all activations from the activation register.

Kind: static method of activationPoints

activationPoints.get() ⇒ Array.<Activation>

Fetch all activations.

Kind: static method of activationPoints
Returns: Array.<Activation> - Found extension points

extensionPoints : object

This object contains a register of extension points and the means to work with them.

Kind: global namespace

• extensionPoints : object
  • .add(name) ⇒ void
  • .remove(name) ⇒ void
  • .register(ep, extension, response, [priority]) ⇒ void
  • .unregisterAll(name)
  • .get([ep]) ⇒ Object.<ExtensionPoint> | ExtensionPoint
  • .execute(name, [input]) ⇒ Array
  • .executeSerial(name, [input]) ⇒ Promise.<*>

extensionPoints.add(name) ⇒ void

Create new extension point and add it to the registry.

Kind: static method of extensionPoints

Param	Type	Description
name	string	Name of the extension point.

extensionPoints.remove(name) ⇒ void

Remove an extension point from the registry.

Kind: static method of extensionPoints

Param	Type	Description
name	string	Name of the extension point

extensionPoints.register(ep, extension, response, [priority]) ⇒ void

Create extension point if it does not exist and then register the given extension to it.

Kind: static method of extensionPoints

Param	Type	Default	Description
ep	string		Name of the extension point.
extension	string		Unique name for the extension.
response	Object | Callback		Object to be returned or function to be called by the extension point.
[priority]	number	0	Order priority for execution used for executing in serial.

extensionPoints.unregisterAll(name)

Remove extensions matching regular expression from all extension points.

Kind: static method of extensionPoints

Param	Type	Description
name	RegExp	Matcher for the name of the extension to remove.

extensionPoints.get([ep]) ⇒ Object.<ExtensionPoint> | ExtensionPoint

Fetch extension point by name. or all extension points if no name is given.

Kind: static method of extensionPoints
Returns: Object.<ExtensionPoint> | ExtensionPoint - Found extension points

Param	Type	Description
[ep]	string	Extension point to return

extensionPoints.execute(name, [input]) ⇒ Array

Call all the extensions registered to an extension point synchronously. See execute on ExtensionPoint. Call this at the point in the base code where you want it to be extended.

Kind: static method of extensionPoints
Returns: Array - Result of Promise.all or Promise.allSettled depending on exitOnError

Param	Type	Description
name	string	Name of the extension point to call
[input]	*	Parameter to provide to the extensions if they are a function

extensionPoints.executeSerial(name, [input]) ⇒ Promise.<*>

Calls all the extensions registered to the extension point in serial. See executeSerial on ExtensionPoint Call this at the point in the base code where you want it to be extended.

Kind: static method of extensionPoints
Returns: Promise.<*> - Result of the last extension that was called

Param	Type	Description
name	string	Name of the extension point to call
[input]	*	Parameter to provide to the extensions if they are a function

plugins : object

Helper functions to access the plugin management in the main process. Note that the facade needs to be imported separately as "pluggable-electron/facade" as described above. It is then available on the global window object as describe in the Electron documentation

Kind: global namespace

• plugins : object
  • .install(plugins) ⇒ Promise.<(Array.<Plugin>|false)>
  • .uninstall(plugins, reload) ⇒ Promise.<boolean>
  • .getActive() ⇒ Promise.<Array.<Plugin>>
  • .registerActive() ⇒ Promise.<Array.<Plugin>>
  • .update(plugins, reload) ⇒ Promise.<Array.<Plugin>>
  • .updatesAvailable(plugin) ⇒ Object.<(string|false)>
  • .toggleActive(plugin, active) ⇒ Promise.<Plugin>

plugins.install(plugins) ⇒ Promise.<(Array.<Plugin>|false)>

Install a new plugin.

Kind: static method of plugins
Returns: Promise.<(Array.<Plugin>|false)> - plugin as defined by the main process. Has property cancelled set to true if installation was cancelled in the main process.

Param	Type	Description
plugins	Array.<(installOptions|string)>	A list of NPM specifiers, or installation configuration objects.

plugins.uninstall(plugins, reload) ⇒ Promise.<boolean>

Uninstall provided plugins

Kind: static method of plugins
Returns: Promise.<boolean> - Whether uninstalling the plugins was successful.

Param	Type	Description
plugins	Array.<string>	List of names of plugins to uninstall.
reload	boolean	Whether to reload all renderers after updating the plugins.

plugins.getActive() ⇒ Promise.<Array.<Plugin>>

Fetch a list of all the active plugins.

Kind: static method of plugins
Returns: Promise.<Array.<Plugin>> - List of plugins as defined by the main process.

plugins.registerActive() ⇒ Promise.<Array.<Plugin>>

Register all the active plugins.

Kind: static method of plugins
Returns: Promise.<Array.<Plugin>> - List of plugins as defined by the main process.

plugins.update(plugins, reload) ⇒ Promise.<Array.<Plugin>>

Update provided plugins to its latest version.

Kind: static method of plugins
Returns: Promise.<Array.<Plugin>> - Updated plugin as defined by the main process.

Param	Type	Description
plugins	Array.<string>	List of plugins to update by name.
reload	boolean	Whether to reload all renderers after updating the plugins.

plugins.updatesAvailable(plugin) ⇒ Object.<(string|false)>

Check if an update is available for provided plugins.

Kind: static method of plugins
Returns: Object.<(string|false)> - Object with plugins as keys and new version if update is available or false as values.

Param	Type	Description
plugin	Array.<string>	List of plugin names to check for available updates.

plugins.toggleActive(plugin, active) ⇒ Promise.<Plugin>

Toggle a plugin's active state. This determines if a plugin should be loaded in initialisation.

Kind: static method of plugins
Returns: Promise.<Plugin> - Updated plugin as defined by the main process.

Param	Type	Description
plugin	String	Plugin to toggle.
active	boolean	Whether plugin should be activated (true) or deactivated (false).

setup(options) ⇒ void

Set the renderer options for Pluggable Electron. Should be called before any other Pluggable Electron function in the renderer

Kind: global function

Param	Type	Default	Description
options	Object
options.importer	importer		The callback function used to import the plugin entry points.
[options.presetEPs]	Boolean | null	false	Whether the Extension Points have been predefined (true), can be created on the fly(false) or should not be provided through the input at all (null).

Extension : Object

An extension registered to an extension point

Kind: global typedef
Properties

Name	Type	Description
name	string	Unique name for the extension.
response	Object | Callback	Object to be returned or function to be called by the extension point.
[priority]	number	Order priority for execution used for executing in serial.

installOptions : Object.<string, any>

The pacote options used to install the plugin.

Kind: global typedef

Param	Type	Default	Description
specifier	string		the NPM specifier that identifies the package.
[activate]	boolean	true	Whether this plugin should be activated after installation.

importer ⇒ module

Used to import a plugin entry point. Ensure your bundler does no try to resolve this import as the plugins are not known at build time.

Kind: global typedef
Returns: module - The module containing the entry point function.

Param	Type	Description
entryPoint	string	File to be imported.