@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.