Manatee v2.1

Appearance

Plugins and modules ​

A plugin is a component that can be started and stopped and may provide some functionality while it is running. An example is the Sectra plugin which interfaces with the Sectra application and provides a bridge between its built-in context manager and the context manager embedded in Manatee.

A module is a component that provides an API for use in flows.

The Plugin module can be used to dynamically load extra functionality in the form of modules and customized context-participants or new and customized application types. The Module module has similar functionality but for modules that provide an API for use in flows.

Generally additional modules come in two flavours; those that must simply be loaded (new modules for the Javascript runtime and new context-participants) and those requiring configuration and which may be active and runnable.

Loading a plugin ​

You need to know the name and version of a plugin to load it.

javascript
Plugin.load("MyPlugin", "v1.0.0");
// Assuming MyPlugin contains a module called MyModule, you can now do something like:
MyModule.doSomething("foo", 1000);

Note that MyPlugin and MyModule are simply examples and the above snippet will fail because the plugin and module do not exist.

Starting and configuring a plugin ​

javascript
// Note: Only one instance of each plugin identified by its name and version are allowed
Plugin.start("MyPlugin", "v1.0.0", { ConfParam1: "foo", ConfParam2: 100 });

The plugin should now be started and its functionality activated - whatever that may be.

Stop a running plugin ​

Deactivates the plugin and its functionality.

javascript
Plugin.stop("MyPlugin", "v1.0.0");

Check the status of a plugin ​

js
var s = Plugin.status("MyPlugin", "v1.0.0");
// if the plugin is runnable then it will have a `state` property
// which will be either "STOPPED" or "RUNNING"
Debug.ger(s.state); 
// it will also contain its configuration
Debug.ger(s.configuration);

Loading a module ​

A Module can be loaded like:

js
var foo = Module.load("foo", { version: 'v1.0.0' });
// and now you can use the functionality provided by "foo"
var bar = foo.bar();

The 2nd argument containing the version is actually optional. If omitted you’ll get the latest version downloaded or if no module has been downloaded then the latest version published.

Controlling module versions globally ​

Two settings provide improved control over which plugin versions are loaded by Module.load.

ExternalPluginVersions ​

ExternalPluginVersions allows you to define default versions for plugins when no version is specified in the Module.load() call.

You can define multiple plugins separated by ;:

text
Fs=v1.2.0; Db=v3.1.0; Crypto=v1.0.0

This makes it possible to:

  • manage plugin versions centrally
  • test new versions on specific machines without modifying flows

Example:

js
// ExternalPluginVersions = "Db=v3.1.0"

var db = Module.load("Db"); // Loads v3.1.0

ExternalPluginVersionMustBeExplicit ​

If ExternalPluginVersionMustBeExplicit is set to true, all plugin loads must resolve to a specific version.

A version can be resolved either:

  • directly in the Module.load() call
  • through ExternalPluginVersions

If no version can be resolved, Module.load() will fail.

If set to false, Module.load() will load the latest version of the plugin if no version is specified.

Example:

js
// Explicit version in code
var db = Module.load("Db", { version: "v3.1.0" });

// Or resolved through ExternalPluginVersions
var db = Module.load("Db");

To gain full control over plugin versions across clients:

  1. Set ExternalPluginVersionMustBeExplicit = true
  2. Define plugin versions globally using ExternalPluginVersions
  3. Use Module.load(pluginName) without specifying versions in flows
  4. Override settings locally when testing new plugin versions

Unloading a module ​

You can actively unload a module if you do not need it anymore:

js
Module.unload("foo", { version: "v1.0.0" });

List modules ​

If you want to see which modules are globally available you can do:

js
var modules = Module.list(Module.GLOBALSCOPE);

This will give you a list of all modules either already downloaded or available for download. If you just want the modules already downloaded, then you can do:

js
var downloadedModules = Module.list(Module.LOCALSCOPE);