@webprovisions/platform v1.1.4

@webprovisions/platform

• About
• The Environment
• Implementations
  • The configuration object
• Widgets
  • Creating a widget at runtime
  • Widget life cycle
  • Widget type

About

Webprovisions is a web distribution platform provided by Humany. The client framework orchestrates widgets and plugins and provides an easy-to-use API for controlling and extending their behaviour.

This package contains core modules for the Webprovisions client framework.

The Environment

In a Webprovisions setup, the main object is a singleton instance of the Environment class, which is often assigned to a property on the global context, e.g. window. It is used to create, manage and configure implementations and widgets.

// Create an instance using the default factory method.
const env = window.myBrand = Environment.create();

Implementations

Implementations provide a way to group widgets to logical units, which is benifitial not only in a multi-tenant setup, but also if your architecture requires that additional resources (such as JavaScript and style sheets) are distributed to specific sets of widgets.

The configuration object

An implementation is identified by its key and tenant properties, specified as part of the configuration object passed to the createImplementation() function on the environment.

const implementation = env.createImplementation({
  name: 'default',
  tenant: 'acme',
  widgets: { /* widget data map */ },
});

The configuration object accepts all required data to fully construct the implementation and its included widgets and plugins. In a complete setup this configuration is normally either fetched from a remote service at runtime or embedded in the distributed bundle.

The widget data map

The widgets property of the implementation configuration is an object map containing configuration data for widgets inside the implementation.

{
  name: 'default',
  tenant: 'acme',
  widgets: { 
    myWidget1: {
      type: '@acme/widget-type',
      settings: { /* arbitrary settings for the widget */ },
    },
  },
}

Widgets

A widget consists of a $widget object, normally referred to as "the widget", and the $instance object which is the instantiated widget type controlling the actual style and behaviour of the visual widget interface.

Creating a widget at runtime

In addition to creating widgets as part of the implementation configuration, a widget can also be created manually using the createWidget() factory on the implementation.

const myWidget2 = implementation.createWidget('myWidget2', {
  type: '@acme/widget-type',
  settings: { /* arbitrary settings for the widget */ },
});

Widget life cycle

The $widget object can be in any of the following states:

deactivated

This is the default state.

In this phase no configuration commands have yet been applied, plugins included, and it does not yet have its $instance object constructed.

widget.state; // 'deactivated'
widget.container.get('$type'); // undefined
widget.container.get('$instance'); // undefined
widget.container.get('$plugins'); // undefined
widget.invoke('command'); // invalid - command will be ignored

From a deactivated state the widget can transition to the activating state by calling activate() on the widget.

activating

In this phase the widget will transition to the activated state. The $instance object is constructed by a call to its constructor. Configuration commands, including plugin instantiation, are applied after. At the end of the phase a call to the $instance.initialize() is made before the widget enters the activated state.

activated

In this phase the widget is fully configured and ready to receive commands. Commands are the widgets public API and it's up to each widget type to define which commands are available.

widget.activate().then(() => {
  widget.state; // 'activated'
  widget.container.get('$type'); // '@acme/widget-type'
  widget.container.get('$instance'); // instanceof $type
  widget.container.get('$plugins'); // array of plugins
  widget.invoke('command'); // command is delegated to the $instance object
});

This state will persist until a call to deactivate() is made.

widget.deactivate(); // widget will transition to 'deactivating' state

deactivating

In this phase the widget will transition to the deactivated state. The deactivate() hook will execute on the $instance object as well as on any registered plugin. At the end of the phase the widget's Container and EventManager are cleared before the widget is restored to its initial deactivated state.

Widget type

A widget type is represented by a JavaScript class extended from WidgetType with a constructor receiving a Container instance as its only argument.

import { WidgetType } from '@webprovisions/platform';

class MyWidgetType extends WidgetType {
  constructor(container) { }
  initialize() { }
  activate(data) { }
  deactivate() { }
}

constructor(container: Container)

Is called during initialization of the widget. At this stage not all configuration commands have been applied. This is a place to register values on the container that you want runtime configurations or plugins to be able to override. To safely read values from the container, use the initialize() hook.

class MyWidgetType extends WidgetType {
  constructor(container) {
    super(container);
    container.register('message', 'Hello world!');
  }
}

initialize()

Is called as the final step during initialization of a widget. At this stage configuration commands have been applied and plugins have been created. Here you may safely read from the container.

class MyWidgetType extends WidgetType {
  constructor(container) {
    super(container);
    container.register('message', 'Hello world!');
  }

  initialize() {
    console.log(this.container.get('message'));
  }
}

activate(data)

Is called during the activating phase, which may be triggered manually by calling activate() on the Widget object, or it may be triggered by the bootstrapping extensions. This is where you should render the widget.

class MyWidgetType extends WidgetType {
  // ...
  activate(data) {
    const message = this.container.get('message');
    const { widgetDOMElement } = data;
    const content = document.createElement('div');
    content.innerHTML = message;
    widgetDOMElement.appendChild(content);
    this.container.register('widgetDOMElement', widgetDOMElement);
  }
}

deactivate()

Is called during the deactivating phase. This is where you should release any bound resources to avoid memory leaks. The Container and EventManager is automatically cleared by the runtime.

class MyWidgetType extends WidgetType {
  // ...
  deactivate() {
    const widgetDOMElement = this.container.get('widgetDOMElement');
    while (widgetDOMElement.firstChild) {
      widgetDOMElement.removeChild(widgetDOMElement.firstChild);
    }
  }
}

Configuration

In a Webprovisions setup widgets are configured via the implementation they belong to. Configuration commands are stored on the implementation and applied to each matching widget. This makes it possible to apply configurations before widgets have been created on the implementation.

Pass a callback to the configure() function on the implementation. During initialization the callback will be called and passed a Configurator object. The configurator contains all available configuration commands.

implementation.configure((config) => {
  config.someCommand({});
});

The configurator can also be used as a function that accepts a WidgetSelector. It returns a configurator object containing all available configuration commands. This can be used to filter which widgets should be affected.

implementation.configure((config) => {
  // filter on type
  config({ type: '@acme/widget-type' }).someCommand({});
  // filter on widget name
  config({ widget: 'myWidget1' }).someCommand({});
});

Configuring via the environment object

When using the bootstrapping extensions from @webprovisions/bootstrapping a configure() function is added to the environment object. This function is a mapper that will delegate the configuration callback to all available implementations on the environment, or a subset of implementations if an ImplementationSelector is specified as the first argument.

myBrand.configure((config) => {
  // configure all implementations
});
myBrand.configure('default', (config) => {
  // configure all implementations named 'default'
});
myBrand.configure({ tenant: 'acme'}, (config) => {
  // configure all implementations for tenant 'acme'
});

Default configuration commands

The following configuration commands are defined by the framework.

types.register(key: string, type: Class<WidgetType>)

Registers a widget type on the specified key. The constructed instance of the specified type is available on the Container by the $instance key.

type(key: string)

Specifies which widget type should be bound. The widget type must be registered through types.register(). Is available on the Container by the $type key.

settings(data: any)

Registers settings. Is available on the Container by the $settings key.

plugin(plugin: Class<Plugin>)

Registers a plugin. The constructed instance of the specified type is added to the $plugins array on the Container.

container.register(key: string, value: any)

Shorthand for register of the current widget's Container instance.

container.registerAsync(key: string, factory: () => any)

Shorthand for registerAsync of the current widget's Container instance.

container.touch(key: string, handler: (value: any) => void)

Shorthand for touch of the current widget's Container instance.

Plugins

Plugins can be registered through the plugin() configuration command.

implementation.configure((config) => {
  config.plugin(MyPlugin);
});

A plugin can be a pure JavaScript function or a constructable class.

Plugin class

class MyPlugin {
  constructor(container, settings) { }
  initialize() { }
  activate() { }
  deactivate() { }
}

Plugin function

const MyPlugin = (container, settings) => {
  // i'm equivalent to `initialize()` in a plugin class
};