| sidebar | auto |
|---|
A widget is an HTML document which can be added to a VisualBox dashboard to visualize data that is provided by integrations. The widget will be notified when data becomes available or is changed, and can react accordingly.
The HTML document will be put inside of an <iframe> with the sandbox attribute applied. The sandbox attribute applies restrictions on what a widget can do, such as running scrips and allow popups.
The following restrictions are lifted:
| Restriction | Description |
|---|---|
allow-forms |
Allows the resource to submit forms. |
allow-modals |
Lets the resource open modal windows. |
allow-pointer-lock |
Lets the resource use the Pointer Lock API. |
allow-popups |
Allows popups (such as window.open(), target="_blank", or showModalDialog()). |
allow-scripts |
Lets the resource run scripts. |
When you create a new widget you have the option to choose a pre-defined HTML template. The template provides a starting point for an HTML document and example code that shows how to read and react to data changes.
The HTML code must be written in an index.html file located in the widget root folder.
There are two events that a widget can react to:
- Change of the configuration model
- Change of the data provided by an integration
You must implement an event handler for each of these events in order to take appropriate actions in your widget code.
Register an event handler by calling visualbox.onConfigChanged(callback). The callback parameter will be invoked by the VisualBox system whenever the configuration model is changed. The parameter passed to the callback is a key-value map of the new configuration model.
Example on how to change the font color:
visualbox.onConfigChanged(function (config) {
document.getElementsByTagName('BODY')[0].style.color = config.color;
});Register an event handler by calling visualbox.onDataChanged(callback). The callback parameter will be invoked by the VisualBox system whenever the connected data source provides new data to be visualized. The parameter passed to the callback contains the new value.
Example on how to show the new data in a <pre> tag:
visualbox.onDataChanged(function (data) {
document.getElementsByTagName('BODY')[0].innerHTML = '<pre>' + data + '</pre>';
});Every widget will have access to the global visualbox object.
| Property | Type | Description |
|---|---|---|
config |
object |
A key-value map of the most recent configuration model. |
data |
any |
The most recently published value of the connected data source. Initially undefined if no value has been received. |
visualbox.onConfigChanged( function callback )
Register an event handler for reacting to configuration changes.
| Parameter | Type | Description |
|---|---|---|
callback |
function |
An event handler to be called whenever the configuration model changes. VisualBox will invoke callback and pass the new configuration model as the first parameter. |
visualbox.onDataChanged( function callback )
Register an event handler for reacting to data changes.
| Parameter | Type | Description |
|---|---|---|
callback |
function |
An event handler to be called whenever the connected data source produces a new value. VisualBox will invoke callback and pass the new value as the first parameter. |