phosphor-plugins
A module for building plugin-based applications.
Package Install
Prerequisites
npm install --save phosphor-plugins
Source Build
Prerequisites
git clone https://github.com/phosphorjs/phosphor-plugins.gitcd phosphor-pluginsnpm install
Rebuild
npm run cleannpm run build
Run Tests
Follow the source build instructions first.
# run tests in Firefox npm test # run tests in Chrome npm run test:chrome # run tests in IE npm run test:ie
Build Docs
Follow the source build instructions first.
npm run docs
Navigate to docs/index.html
.
Build Examples
Follow the source build instructions first.
npm run build:examples
Navigate to one of the examples/
and start a server.
Supported Runtimes
The runtime versions which are currently known to work are listed below. Earlier versions may also work, but come with no guarantees.
- IE 11+
- Firefox 32+
- Chrome 38+
Plugin Specification
Plugins are specified with a top-level phosphor-plugin.json
file placed in
the root directory of a package. When a plugin named foo
is registered, the
foo/phosphor-plugin.json
file will be imported and used for configuration.
The phosphor-plugin.json
file is an object with the following properties:
extensionPoints
- Optional. An array of extension point specifications.extensions
- Optional. An array of extension specifications.
An extension point is specified as an object with the following fields:
id
- Required. The globally unique id of the extension point.main
- Optional. The path to the extension point main module. This path is assumed to be relative to the plugin. For example, for a plugin namedfoo
and an extension pointmain
path oflib/index.js
, thefoo/lib/index.js
module is loaded.factory
- Optional. The name of a function in themain
module which creates the receiver for the extension point. The function should take no arguments and returnvoid | IReceiver | Promise<IReceiver>
.
An extension is specified as an object with the following fields:
id
- Required. The globally unique id of the extension.point
- Required. The identifier of the target extension point.main
- Optional. The path to the extension main module. This path is assumed to be relative to the plugin. For example, for a plugin namedbar
and an extensionmain
path oflib/index.js
, thebar/lib/index.js
module is loaded.factory
- Optional. The name of a function in themain
module which creates the contribution for the extension. The function should take no arguments and returnvoid | IContribution | Promise<IContribution>
.data
- Optional. The path to the JSON data file for the extension. Some extension points are able to consume data from JSON files, such as menu and key binding specifications. This path is relative to the plugin.config
- Optional. Extra static configuration data for the extension. Some extension points are able to consume static configuration data along with the actual extension object.
Paths are loaded using System.import
, which must be configured to load the
plugin package by name. See the examples/
folder for configurations using
SystemJS
and StealJS
.
Usage Examples
Note: This module is fully compatible with Node/Babel/ES6/ES5. Simply omit the type declarations when using a language other than TypeScript.
Register a plugin and load its JSON specification. The plugin's extensions and extension points are automatically registered. For each extension, the registry is scanned for a matching extension point. If a match is found, the extension and extension point are instantiated and paired.
; ; console.loglistPlugins; // ['my-plugin'] disposable.dispose; // unregister and unload the plugin
Dynamically register an extension point which is created at runtime:
; ; registerExtensionPointpoint;
Dynamically register an extension which is created at runtime:
; ; registerExtensionext;