@humany/widget-types-bot

The Bot widget consists of a trigger element (triggerDOMElement) and a main widget element (widgetDOMElement).

General commands

The following commands are part of the Widget API and are available for all widget types.

initialize(): Promise

No custom behaviour.

activate([options: BotWidgetActivationOptions]): Promise

Creates new instances of triggerDOMElement and widgetDOMElement. The triggerDOMElement is directly appended to the DOM whereas the widgetDOMElement is not appended until later.

After activation, the elements are available on the Container:

const widgetDOMElement = container.get('widgetDOMElement');
const triggerDOMElement = container.get('triggerDOMElement');

BotWidgetActivationOptions: object

The following options can be specified when activating the widget:

widgetDOMElement: HTMLElement (optional) - Set this option if you want the widget to be rendered inside an existing element. This can be used in cases when you have a dedicated area on the page where you want the widget to be displayed, in contrast to the default "floating" behaviour.

Default: undefined (a new element is created).

renderTriggerElement: boolean (optional) - Set this to false if you don't want the triggerDOMElement to be created. The widget must be started manually if no trigger element is available.

Default: true

deactivate(): Promise

Invokes moveOutsideViewport() and then removes widgetDOMElement and triggerDOMElement.

Bot commands

Regular commands can be invoked after the widget has been activated.

connect([initialCommands: object]): Promise

Connects the underlying MessageClient with the remote Humany service.

sendCommands(commands: object): Promise

Dispatches one or many commands on the underlying DataSource. This will connect the DataSource if not already connected.

moveInsideViewport(): void

Positions the widgetDOMElement inside the viewport relative to the triggerDOMElement. Together with CSS transitions this will create an animation where the widget is sliding in.

moveOutsideViewport(): void

Positions the widgetDOMElement outside the viewport relative to the triggerDOMElement. Together with CSS transitions this will create an animation where the widget is sliding out.

start(): void

Shorthand command that sequentially invokes connect() or sendCommands() (depending on whether the DataSource is connected or not) and then moveInsideViewport().

Services

Both asynchronous and synchronous services are available on the Container:

Async services:

// ES stage 3 syntax
const theService = await container.getAsync('theService');

// ES6 syntax
container.getAsync('theService').then((theService) => {

});

Sync services:

const theService = container.get('theService');

The following service is registered when a Bot widget is created.

'data' (DataSource)

Handles the communication with the remote service. See the @humany/widget-data package.

Accessing the widget from a Plugin

When extending from the Webprovisions.Platform.Plugin class, the widget is accessible on this.widget. Use the invoke() function to invoke commands on the widget API:

import { Plugin } from '@humany/widget-core';

class MyPlugin extends Plugin {
  initialize() {
    this.widget.invoke('start');
  }
}

See the Skeleton Plugin repository for an example on how to author a Webprovisions plugin.