# @webprovisions/platform

> Webprovisions core platform modules.

Latest version **1.1.4** (published 2023-08-11) · SEE LICENSE IN LICENSE.txt license · 0 weekly downloads

## Install

```sh
npm install @webprovisions/platform
pnpm add @webprovisions/platform
yarn add @webprovisions/platform
bun add @webprovisions/platform
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.4 |
| Published | 2023-08-11 |
| First published | 2018-02-05 |
| Weekly downloads | 0 |
| License | SEE LICENSE IN LICENSE.txt |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 170.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Telia Company AB |
| Maintainers | donami, bratn, totte |
| Keywords | webprovisions |

## Links

- npm: https://www.npmjs.com/package/@webprovisions/platform
- npm.io page: https://npm.io/package/@webprovisions/platform

## Recent versions

- 1.1.4 (latest) — 2023-08-11
- 1.1.3-rc.3 (rc) — 2023-06-05
- 1.1.3 — 2023-08-09
- 1.1.3-rc.2 — 2023-06-05
- 1.1.3-rc.1 — 2023-06-02
- 1.1.2 — 2022-02-17
- 1.1.1 — 2021-03-11
- 1.1.0 — 2020-04-08
- 1.0.8 — 2020-02-14
- 1.0.7 — 2019-11-15
- 1.0.6 — 2019-08-12
- 1.0.5 — 2019-06-18
- 1.0.4 — 2019-06-11
- 1.0.3 — 2019-05-02
- 1.0.2 — 2019-04-16
- … 30 more at https://npm.io/package/@webprovisions/platform/versions

## README

# @webprovisions/platform
![Build Status](https://humany.visualstudio.com/humany-core/_apis/build/status/webprovisions?branchName=master)

* [About](#about)
* [The Environment](#the-environment)
* [Implementations](#implementations)
  - [The configuration object](#the-configuration-object)
* [Widgets](#widgets)
  - [Creating a widget at runtime](#creating-a-widget-at-runtime)
  - [Widget life cycle](#widget-life-cycle)
  - [Widget type](#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.

```js
// 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.
```js
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. 
```js
{
  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.
```js
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.
```js
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.  </br>
The `$instance` object is constructed by a call to its constructor. Configuration commands, including plugin instantiation, are applied after. </br>
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.  </br>
Commands are the widgets public API and it's up to each widget type to define which commands are available.
```js
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.
```js
widget.deactivate(); // widget will transition to 'deactivating' state
```

#### `deactivating`
In this phase the widget will transition to the `deactivated` state.  </br>
The `deactivate()` hook will execute on the `$instance` object as well as on any registered plugin. </br> 
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.

```js
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. </br> 
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.
```js
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. </br> 
At this stage configuration commands have been applied and plugins have been created. Here you may safely read from the container.
```js
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. </br> 
This is where you should render the widget.
```js
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. </br> 
This is where you should release any bound resources to avoid memory leaks. The `Container` and `EventManager` is automatically cleared by the runtime.
```js
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.
```js
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.
```js
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.
```js
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. 
```js
implementation.configure((config) => {
  config.plugin(MyPlugin);
});
```
A plugin can be a pure JavaScript function or a constructable class.
### Plugin class
```js
class MyPlugin {
  constructor(container, settings) { }
  initialize() { }
  activate() { }
  deactivate() { }
}
```
### Plugin function
```js
const MyPlugin = (container, settings) => {
  // i'm equivalent to `initialize()` in a plugin class
};
```

---
_Source: https://npm.io/package/@webprovisions/platform · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._