Skip to content

Plugin manager API

Jump to bottom
igor edited this page Oct 27, 2022 · 8 revisions

API definition for using Pluggable Electron in the main process

Managing the Pluggable Electron plugin registry and handling the plugin files is done using the plugin manager in the main process. Files are stored and the registry is persisted in a plugin folder provided by the consumer. Initialise the plugin to load the registry from file with the init function.

The plugin manager can be imported in the main process by requiring pluggable electron. E.g. const pe = require("pluggable-electron")

Classes

Plugin

An NPM package that can be used as a Pluggable Electron plugin. Used to hold all the information and functions necessary to handle the plugin lifecycle.

Functions

init(options) ⇒ pluginManager | Object

Sets up the required communication between the main and renderer processes. Additionally sets the plugins up using usePlugins if a pluginsPath is provided.

usePlugins(pluginsPath) ⇒ pluginManager

Set Pluggable Electron up to run from the pluginPath folder if it is provided and load plugins persisted in that folder.

getStore() ⇒ pluginManager

Returns the publicly available store functions.

Typedefs

confirmInstall ⇒ Promise.<boolean>

This function is executed when plugins are installed to verify that the user indeed wants to install the plugin.

installOptions : Object.<string, any>

The pacote options used to install the plugin with some extra options.

pluginManager : Object

Provides access to the plugins stored by Pluggable Electron

Plugin

An NPM package that can be used as a Pluggable Electron plugin. Used to hold all the information and functions necessary to handle the plugin lifecycle.

Kind: global class

new Plugin([origin], [options])

Set installOptions with defaults for options that have not been provided.

Param Type Description
[origin] string Original specification provided to fetch the package.
[options] Object Options provided to pacote when fetching the manifest.

plugin.specifier : string

Package name with version number.

Kind: instance property of Plugin

plugin.active : boolean

Whether the plugin should be registered with its activation points.

Kind: instance property of Plugin

plugin.subscribe(name, cb)

Subscribe to updates of this plugin

Kind: instance method of Plugin

Param Type Description
name string name of the callback to register
cb callback The function to execute on update

plugin.unsubscribe(name)

Remove subscription

Kind: instance method of Plugin

Param Type Description
name string name of the callback to remove

plugin.update(version) ⇒ boolean

Check for updates and install if available.

Kind: instance method of Plugin
Returns: boolean - Whether an update was performed.

Param Type Default Description
version string false The version to update to.

plugin.isUpdateAvailable() ⇒

Check if a new version of the plugin is available at the origin.

Kind: instance method of Plugin
Returns: the latest available version if a new version is available or false if not.

plugin.uninstall() ⇒ Promise

Remove plugin and refresh renderers.

Kind: instance method of Plugin

plugin.setActive(active) ⇒ Plugin

Set a plugin's active state. This determines if a plugin should be loaded on initialisation.

Kind: instance method of Plugin
Returns: Plugin - This plugin

Param Type Description
active boolean State to set _active to

init(options) ⇒ pluginManager | Object

Sets up the required communication between the main and renderer processes. Additionally sets the plugins up using usePlugins if a pluginsPath is provided.

Kind: global function
Returns: pluginManager | Object - A set of functions used to manage the plugin lifecycle if usePlugins is provided.

Param Type Default Description
options Object configuration for setting up the renderer facade.
[options.confirmInstall] confirmInstall Function to validate that a plugin should be installed.
[options.useFacade] Boolean true Whether to make a facade to the plugins available in the renderer.
[options.pluginsPath] string Optional path to the plugins folder.

usePlugins(pluginsPath) ⇒ pluginManager

Set Pluggable Electron up to run from the pluginPath folder if it is provided and load plugins persisted in that folder.

Kind: global function
Returns: pluginManager - A set of functions used to manage the plugin lifecycle.

Param Type Description
pluginsPath string Path to the plugins folder. Required if not yet set up.

getStore() ⇒ pluginManager

Returns the publicly available store functions.

Kind: global function
Returns: pluginManager - A set of functions used to manage the plugin lifecycle.

confirmInstall ⇒ Promise.<boolean>

This function is executed when plugins are installed to verify that the user indeed wants to install the plugin.

Kind: global typedef
Returns: Promise.<boolean> - Whether to proceed with the plugin installation

Param Type Description
plg Array.<string> The specifiers used to locate the packages (from NPM or local file)

installOptions : Object.<string, any>

The pacote options used to install the plugin with some extra options.

Kind: global typedef

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

pluginManager : Object

Provides access to the plugins stored by Pluggable Electron

Kind: global typedef
Properties

Name Type
getPlugin getPlugin
getAllPlugins getAllPlugins
getActivePlugins getActivePlugins
installPlugins installPlugins
removePlugin removePlugin

pluginManager.getPlugin(name) ⇒ Plugin

Get a plugin from the stored plugins.

Kind: static method of pluginManager
Returns: Plugin - Retrieved plugin

Param Type Description
name string Name of the plugin to retrieve

pluginManager.getAllPlugins() ⇒ Array.<Plugin>

Get list of all plugin objects.

Kind: static method of pluginManager
Returns: Array.<Plugin> - All plugin objects

pluginManager.getActivePlugins() ⇒ Array.<Plugin>

Get list of active plugin objects.

Kind: static method of pluginManager
Returns: Array.<Plugin> - Active plugin objects

pluginManager.removePlugin(name, persist) ⇒ boolean

Remove plugin from store and maybe save stored plugins to file

Kind: static method of pluginManager
Returns: boolean - Whether the delete was successful

Param Type Description
name string Name of the plugin to remove
persist boolean Whether to save the changes to plugins to file

pluginManager.installPlugins(plugins, [store]) ⇒ Promise.<Array.<Plugin>>

Create and install a new plugin for the given specifier.

Kind: static method of pluginManager
Returns: Promise.<Array.<Plugin>> - New plugin

Param Type Default Description
plugins Array.<(installOptions|string)> A list of NPM specifiers, or installation configuration objects.
[store] boolean true Whether to store the installed plugins in the store
Clone this wiki locally