Plugin platform interface

These are the core APIs which allow your plugin to integrate into the Haplo Platform.

Interface

function hook(name, responderFunction)

You can call hook() more than once to register multiple functions for the same hook.

See the Hooks documentation for example code for each hook.

function callback(name, responderFunction)

Create a callback from responderFunction with the given name (which must not be used for another callback in the same plugin).

A descriptor for the callback is returned, which can be passed to API functions that require a callback descriptor. When the callback is invoked via that descriptor, responderFunction will be called with any arguments provided by the caller.

The returned descriptor is an opaque value. Your code must not assume it is any particular data type or attempt to serialise it.

function element(name, description, renderer)

Implement an Element, and enable the default implementations of hElementDiscover and hElementRender.

name is the name of the Element. The plugin name will automatically be added as a prefix, so if the name is "home", an Element name like example_plugin:home will be generated.

description is a short description of the Element, for displaying to the system administrator when the available Elements are listed.

renderer is a function which will be called to generate the HTML for the element. It’ll be called with this set to the Plugin object. The renderer function takes a single argument, a PluginElementRenderer object, and by convention, this argument should be named L. See Elements for details on how to implement an Element.

function workUnit(implementation)

Implement support for a WorkUnit using the given implementation, a JavaScript object with the following properties:

workType is the work type for the WorkUnits. The plugin name will automatically be added as a prefix, so if the name is "action", a WorkUnit name like example_plugin:action will be generated.

description is a short description of the work unit, for displaying to the application administrator.

render is a function which will be called to generate the HTML for the element. It’ll be called with this set to the Plugin object. The function takes a single argument, a PluginWorkUnitRenderer object, and by convention, this argument should be named W.

See Workflow for details on how to implement a WorkUnit.

function implementService(name, serviceFunction)

Implement a service for inter-plugin communication. The serviceFunction will be called with this set to the Plugin object when the service is called using O.service().

The service name must include a ‘:’ character, as by convention, the service name uses a namespace. For example, you might name a service "example_plugin:do_something".

If more than one plugin implements the same service, the functions will be called in order of registration, until one returns something other than undefined.

Services should be registered during evaluation of the plugin scripts, but are only available after all the plugin scripts have been loaded. This ensures that you’re not accidentally relying on the order that plugins are loaded.

function provideFeature(name, injectFunction)

Implement a ‘feature’ for other plugins to use. This allows common code for a set of plugins to be encapsulated in another plugin, avoiding duplication or clumsy code. Always consider using a service, rather than a feature.

The feature name must include a ‘:’ character, as by convention, the feature name uses a namespace.

injectFunction is called with a argument of the plugin which uses the feature. This is permitted to do anything appropriate to inject the feature into the using plugin. For example:

var add = function(a, b) { return a + b; }
P.provideFeature("example:addition", function(plugin) {
    plugin.add = add;
});

The loadPriority of the providing plugin should be lower than that of any plugin using the feature.

function use(name)

Use the named feature in a plugin. The providing plugin may make any modifications to your plugin object.

In general, you should should use a use directive in your plugin.json.