phosphor-plugins v0.4.0

phosphor-plugins

A module for building plugin-based applications.

API Docs

Package Install

Prerequisites

• node

npm install --save phosphor-plugins

Source Build

Prerequisites

• git
• node

git clone https://github.com/phosphorjs/phosphor-plugins.git
cd phosphor-plugins
npm install

Rebuild

npm run clean
npm 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 named foo and an extension point main path of lib/index.js, the foo/lib/index.js module is loaded.
• factory - Optional. The name of a function in the main module which creates the receiver for the extension point. The function should take no arguments and return void | 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 named bar and an extension main path of lib/index.js, the bar/lib/index.js module is loaded.
• factory - Optional. The name of a function in the main module which creates the contribution for the extension. The function should take no arguments and return void | 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.

import {
  listPlugins, registerPlugin
} from 'phosphor-plugins';

let disposable = registerPlugin('my-plugin');

console.log(listPlugins());  // ['my-plugin']

disposable.dispose();        // unregister and unload the plugin

Dynamically register an extension point which is created at runtime:

import {
  IExtensionPoint, registerExtensionPoint
} from 'phosphor-plugins';

let point: IExtensionPoint = {

  id: 'my-plugin:my-dynamic-point',

  plugin: 'my-package',

  isDisposed: false,

  dispose: () => {
    point.isDisposed = true;
    console.log('disposed');
  },

  add: extension => {
    console.log('Add extension', extension.id, extension.item);
  },

  remove: id => {
    console.log('Remove extension', id);
  },
};

registerExtensionPoint(point);

Dynamically register an extension which is created at runtime:

import {
  IExtension, registerExtension
} from 'phosphor-plugins';

let ext: IExtension = {

  id: 'my-other-plugin:my-dynamic-ext',

  point: 'my-plugin:my-dynamic-point',

  plugin: 'my-other-package',

  item: { value: 42 },

  data: null,

  config: null,

  isDisposed: false,

  dispose: () => {
    ext.isDisposed = true,
    console.log('disposed');
  },
};

registerExtension(ext);