Widgets Library

Introduction
Widget Types
Widgets Library (Bundles)
Operations with Widget
Operations with Widgets Bundle

Introduction

All IoT Dashboards are constructed using ThingsBoard widgets defined in the Widget Library. Widgets are used to display data and visualize information obtained from devices connected to the ThingsBoard platform, remote device control, alarms management, and display static custom HTML content.

According to the provided features, each widget definition represents a specific type of widget. There are five widget types:

Latest values;
Time series;
Control widget;
Alarm widget;
Static widget.

The widget type is displayed in the corresponding column on the "Widget Library" page.

Each widget type has its own specific data source configuration to visualize data. Types of available data source depend on widget type:

Alarm source - this data source type, used primarily in Alarm widgets, requires a source entity to display related alarms and their corresponding fields;
Alarms count - this data source type is used in latest values widgets. You need to specify the target entity;
Device - this data source type is used in both time-series and latest values widgets. Basically, you need to specify the target device, and the time series key, or the attribute name, or entity field;
Entities count - this data source type is used in latest values widgets. You need to specify the target entity;
Entity - this data source type is used in both time-series and latest values widgets. Basically, you need to select the target entity by specifying an entity alias, and the time series key, or the attribute name;
Function - this data source type is used in both time series and latest values widgets for debugging. Basically, you can specify a JavaScript function that will simulate data from a device in order to set up visualization.

Latest values

The Latest values widget type is designed to showcase the latest values of a specific entity attribute or time series data point (e.g., any Gauge Widget or Entities Table widget). This type of widget uses values of entity attribute(s) or time series as a data source. Digital Gauge in example is displaying current temperature value.

Digital Gauge displaying current power value.

Time series

The Time series widget type displays historical values for the selected period of time, or the latest values in the certain time window (e.g., Timeseries Line Chart or Timeseries Bar Chart). This widget type uses only the values of entity time series as a data source. In order to specify the time frame of displayed values, Timewindow settings are used. The timewindow can be specified on the dashboard page or in the widget details. It can be either Realtime - the dynamically changed time frame for a certain latest interval, or History - a fixed historical time frame. All these settings are part of Timeseries widget configuration. In the example, the “Timeseries Line Chart” displays the speed value of device in realtime.

An example of timeseries widget is the "Timeseries Line Chart". It displays amperage values of devices in real-time.

The Control widget allows sending RPC commands to devices, it handles and visualizes reply from the device (e.g., Raspberry Pi GPIO Control) The RPC widgets are configured by specifying the target device as the target endpoint for RPC commands. In the example, the “Basic GPIO Control” widget sends GPIO switch commands and detects the current GPIOs switch status.

RPC widgets are configured by specifying target device as target endpoint for RPC commands;

An example of RPC widget is “Basic GPIO Control”. It sends GPIO switch commands and detects current GPIOs switch status.

The Alarm Widget type displays alarms related to the specified entity in the certain time window (e.g., Alarms table). The Alarm widget is configured by specifying an entity as the alarm source, and the corresponding alarm fields. As the Timeseries widgets, Alarm widgets have the timewindow configuration to specify the time frame of the displayed alarms. Additionally, the configuration includes parameters such as “Alarm status”, “Alarm severity”, and “Alarm type”. The “Alarm status” parameter is used to show the status of the alarms being fetched. The “Alarm severity” parameter shows the frequency of alarm fetches in seconds. The “Alarm Type” parameter helps identify the primary source of the alarm. For instance, “HighTemperature” and “LowHumidity” represent two different alarms. In this context, the “Alarms table” widget displays the latest alarm for the device in real time.

Alarm widget is configured by specifying an entity as the alarm source, and the corresponding alarm fields;

An example of Alarm widget is the “Alarms table” widget that displays the latest alarm for the device in real-time.

Static

The Static widget type displays static customizable HTML content (e.g., HTML card). Static widgets don’t use any data sources and are usually configured by specifying static HTML content and optionally CSS styles. An example of a Static widget is the “HTML card” that displays the specified HTML content.

An example of a Static widget is the “HTML card” that displays the specified HTML content.

An example of a CSS style function to adjust an HTML card style.

.card {
font-weight: bold;
font-size: 32px;
color: #999;
width: 100%;
height: 100%;
display: flex;
align-items: center;
justify-content: center;
}

An example of an HTML code for specifying card content.

<h1>Static widget title</h1>
<div class='card'>Your text here</div>

Widgets Library (Bundles)

Widgets are grouped into widget bundles according to their purposes. Some widgets can be found in multiple packages simultaneously. For example, the Alarm Count widget can be found in the Alarm widgets bundle and the Count widgets bundle.

There are system-level and tenant-level widgets bundles. Initial ThingsBoard installation comes with a basic set of system-level widgets bundles.

The system-level bundles can be managed by a System administrator and are available for use by any tenant in the system. The tenant-level bundles can be managed by a Tenant administrator and are available for use only by this tenant and his customers. You can always implement and add your widgets by following this guide.

To find the widget you need among all the widget bundles, you can use the search function.

You can also find the widget you need by its name on the “Widgets” tab. Here, all available widgets are listed by default in alphabetical order.

Alarm widgets

The Alarm widgets bundle is useful for visualization of alarms for specific entities, both in real-time and history modes.

Analog Gauges

The Analog Gauges bundle is useful for visualization of temperature, humidity, speed, and other integer or float values.

Cards

The Cards bundle is useful for visualization of time series data or attributes in table or card widgets.

For visualization of time series data or attributes in a table or card widgets.

Charts

The Charts bundle is useful for visualization of historical or real-time data with a time window.

Control widgets

The Control widgets bundle is useful for visualization of the current state and sending RPC commands to target devices.

For visualization of current state and sending RPC commands to target devices.

Count widgets

The Counter widgets bundle is useful for counting and visualizing the current number of alarms and entities based on the selected filter.

For counting and visualizing the number of alarms and entities based on the selected filter.

Date widgets

The Date widgets bundle is useful for changing the data range for other widgets on the dashboard.

Digital Gauges

The Digital Gauges bundle is useful for visualization of temperature, humidity, speed and other integer or float values.

Edge widgets

The Edge widgets bundle is useful for an overview of entities related to the specified ThingsBoard Edge instance.

Entity admin widgets

The Entity admin widgets are templates of complex widgets that allow listing and creating/updating/deleting devices and assets.

For listing and creating/updating/deleting devices and assets.

Entity widgets

The Entity admin widgets display a list of entities with their data, counting entities, and display the hierarchy of entities based on their relations.

For displaying a list of entities with their data, counting entities, and displays the hierarchy of entities based on their relations.

Files widgets

The Files widgets display a list of files or PDF reports as a table. Allows to download and delete the file.

For displaying a list of files or PDF reports as a table. Allows to download and delete the file.

Gateway widgets

The Gateway widgets bundle is useful for managing extensions.

GPIO widgets

The GPIO widgets bundle is useful for visualization and controlling GPIO state for target devices.

For visualization and control of GPIO state for target devices.

Home page widgets

The Home page widget bundle is useful for customizing and displaying quick links to the platform’s UI components, documentation, or any other resources on the home page, displaying statistics about the number of entities and API usege, etc.

For customize and display quick links to the platform's UI components, documentation or any other resources on the home page, display statistics about the number of entities and API usage, etc.

HTML widgets

The HTML widgets bundle is useful for injecting custom HTML code. Or for displaying configurable HTML with the ability to inject values from the selected data source.

For injecting custom HTML code. And for displaying configurable HTML with the ability to inject values from the selected data source.

Input widgets

The Input widgets bundle is useful for modifying the attributes of an entity.

Maps widgets

The Map widgets bundle is useful for visualizing the geographic location of devices and tracking device routes in both real-time and history modes.

For visualization of devices' geolocations and tracking devices routes both in real-time and history mode.

The Navigation widgets bundle is useful for defining the home dashboard of the user.

For defining home dashboard of the user.

Scheduling widgets

The Scheduling widgets bundle is useful for scheduling various types of events with flexible schedule configuration.

Tables Widgets

The Tables widget bundle is useful when you need to display a list of entities, a list of alarm signals, and time series data for one or several entities. Additionally, this widget bundle showcases Persistent RPC requests, which are based on entity alias. It can also be filtered optionally and supports pagination for enhanced usability.

For displaying a list of entities, a list of alarm signals, and time series data for one or several entities, and for displaying Persistent RPC requests based on entity alias and optional filter with the ability of pagination.

If the system administrator adds a new widget, it automatically becomes a system one. This means that only the administrator has the privilege to modify, or delete the widget. Tenant administrators can also create widgets. But they have permission to modify only the widgets they created. You can always implement and add your widgets by following this guide.

To add a new widget, you should:

Navigate to the "Widgets Library" page using the main menu on the left. Click the "+" icon in the upper right corner of the screen, and select the "Create new widgets type" option from the drop-down menu;
In the pop-up window select widget type;
In the pop-up window select widget type. In the dialog window that appears, enter the name of the new widget. Enter the widget JavaScript code, then click "Save" to complete the creation of widget;
A new widget is created.

Navigate to the "Widgets Library" page using the main menu on the left. Click the "+" icon in the upper right corner of the screen, and select the "Create new widgets type" option from the drop-down menu;

In the pop-up window select widget type;

In the pop-up window select widget type. In the dialog window that appears, enter the name of the new widget. Enter the widget JavaScript code, then click "Save" to complete the creation of widget;

You can export a specific type of widget from a widget bundle in JSON format, and import it in the same or different ThingsBoard instance.

In order to export a widget type, you should go to the Widgets Library page, navigate to the “Widgets” tab and click the export button on the particular widget card. The widget configuration file will be saved in JSON format on your computer.

Go to the "Widgets Library" page, navigate to the "Widgets" tab, and click the export button on the particular widget card. The widget configuration file will be saved in JSON format on your computer.

Please note that only system administrators can modify system (default) widgets. This means that only they can edit and delete widgets inside the bundle, add or import new widgets into the bundle. When a system administrator creates a new widget bundle, it’s set as a system-level item for tenants, preventing them from modifying it. Nevertheless, tenants can add their own widgets. In this case, they have full rights to manage created widget types inside the bundle.

To import a widget, you should:

Go to the "Widgets Library" page, navigate to the "Widgets" tab, and click the "+" button in the upper right corner of the screen. Select "Import widgets type" from the drop-down menu;
In the popup, you will be prompted to upload the JSON file. Drag and drop a file from your computer, then click the "Import" to add a widget to the widget bundle;
The widget is imported to the bundle.

Go to the "Widgets Library" page, navigate to the "Widgets" tab, and click the "+" button in the upper right corner of the screen. Select "Import widgets type" from the drop-down menu;

The system administrator or tenant administrator can delete a widget type using one of the following ways:

First way:

Go to the "Widgets Library" page, navigate to the "Widgets" tab, and click a "Trash" icon in the widget's type row you want to delete;
Confirm deleting the widget type in the dialog box.

Go to the "Widgets Library" page, navigate to the "Widgets" tab, and click a "Trash" icon in the widget's type row you want to delete;

Confirm deleting the widget type in the dialog box.

Second way:

Go to the "Widgets Library" page, navigate to the "Widgets" tab, and click a "Pencil" icon in the widget's type row to open widget details;
Click on the "Delete widget type" button in the widget details;
Confirm deleting the widget type in the dialog box.

Go to the "Widgets Library" page, navigate to the "Widgets" tab, and click a "Pencil" icon in the widget's type row to open widget details;

Click on the "Delete widget type" button in the widget details;

Operations with Widgets Bundle

Adding Widgets Bundle

If the system administrator adds a new widgets bundle, it automatically becomes a system one. It means that only he can delete, edit, and add widget into the bundle. Tenant administrators can create widgets bundles as well. In this case, they have permissions to modify created bundles. You can always implement and add your widgets by following this guide.

To add a new widgets bundle, you should:

Navigate to the "Widgets bundle" page using the main menu on the left. Click the "+" icon in the upper right corner of the screen, and select the "Create new widgets bundle" option from the drop-down menu;
In the opened dialog window, enter the name of the new bundle. Adding an image and a description is optional. Click "Add";
The new widgets bundle is opened. After adding the widgets bundle, you can add widgets in there. For this, click the "+ Add Widget";
Select one or multiple widgets and click "Save" to complete add widget to your widget bundle;
Since widgets bundles are in alphabetical order, the newly created one may be on the second page.

Navigate to the "Widgets bundle" page using the main menu on the left. Click the "+" icon in the upper right corner of the screen, and select the "Create new widgets bundle" option from the drop-down menu;

In the opened dialog window, enter the name of the new bundle. Adding an image and a description is optional. Click "Add";

The new widgets bundle is opened. After adding the widgets bundle, you can add widgets in there. For this, click the "+ Add Widget";

Select one or multiple widgets and click "Save" to complete add widget to your widget bundle;

Since widgets bundles are in alphabetical order, the newly created one may be on the second page.

Exporting Widgets Bundle

You can export a widgets bundle in JSON format, and import it in the same or different ThingsBoard instance.

In order to export widgets bundle, you should:

Go to the "Widgets Library" page, navigate to the "Widgets Bundle" tab, and click the export button on the specific widgets bundle row;
In the pop-up window, optionally check the "Include bundle widget types in exported data", then click "Export". The widgets bundle configuration file will be saved in JSON format on your computer.

Go to the "Widgets Library" page, navigate to the "Widgets Bundle" tab, and click the export button on the specific widgets bundle row;

In the pop-up window, optionally check the "Include bundle widget types in exported data", then click "Export". The widgets bundle configuration file will be saved in JSON format on your computer.

Importing Widgets Bundle

To import widgets bundle, you should:

Go to the "Widgets Library" page, and click the "+" button in the upper right corner of the "Widgets Bundles" page. Select "Import widgets bundle" from the drop-down menu;
In the popup, you will be prompted to upload the JSON file. Drag and drop a file from your computer, then click "Import" to add a widget bundle to the library;
The widgets bundle is imported

Go to the "Widgets Library" page, and click the "+" button in the upper right corner of the "Widgets Bundles" page. Select "Import widgets bundle" from the drop-down menu;

Deleting Widgets Bundle

The system administrator or tenant administrator can delete a widgets bundle using one of the following ways: