Widget Actions

Widgets

Widget Actions

The Widget Actions feature can be treated as navigation among dashboard states or between different dashboards. Widget Actions allow quick and easy configuring of the transition to created state, transferring to other dashboards, or even updating the dashboard the user is in. Depending on the widget, the action sources differ. However, the type of action the user can choose will be the same for all widgets. Actions can be configured both when editing and creating the required widget.

To fully understand how to use Widget Actions, the user must add a State to the dashboard. Refer to the 'Working with Dashboards - States' section for more details on this.

Add Action

In this step, we will outline only the general steps without going into the details of each setting. Examples of using each type of action and action source will be covered later in the guide for better understanding.

Most widgets offer two configuration options: Basic and Advanced. Accordingly, the process of adding actions differs slightly between these modes. Let’s explore both:

Using the Basic Widget Configuration:

• Enter the editing mode of the widget, scroll down and find the “Actions” menu item

• Click the “Add action” button (once the user has created one or more actions, the “Add actions” button will change to the + icon). The “Actions” window will open. Right now, it’s empty, but later it will display all created actions

• Click the ‘plus’ icon in the top right corner of the screen to open a new “Add action” window. Here the user must configure a new action by entering a name, specifying the action source, and selecting the action type. Further action configuration will depend on the selected action type. Then, click “Add” to proceed

• In the “Actions” window, the user can see the configured action, verify the action source, icon, and action type and click “Save”

• Click “Apply” to save the widget settings

Save the dashboard by clicking “Save” in the upper right corner of the dashboard page.

Using the Advanced Widget Configuration:

• Enter the widget editing mode, and navigate to the “Actions” tab. Currently, it is empty, but later all created actions will be displayed here

• Now, the user can see the configured action, verify the action source, icon, and action type. Click “Save”

• Click “Apply” to save the widget settings

• Save the dashboard by clicking “Save” in the upper right corner of the dashboard page.

Now, the user can use the action. This can involve clicking on a separate button, the widget title, an individual row of entity, etc.

Action Types

The types of action define the specific action that will be taken. There are seven action types that are applicable to all widgets:

Navigate to New Dashboard State - transfers users to the specified state within the current dashboard;
Update Current Dashboard State - updates the dashboard that user is currently on;
Navigate to Other Dashboard - transfers user to a specified dashboard;
Custom Action - allows manual configuration of a function for an individual action on the widget;
Custom Action (with HTML template) - allows manual entry of a function within an existing HTML template;
Mobile Action - allows the use of various mobile device functions such as taking photos, scanning QR codes, getting device location, making phone calls and so on;
Open URL - allows users to go to any resource represented by a URL.

Navigate to New Dashboard State

States are levels that allow users to navigate between different devices, assets, and widget objects to see the information needed in more detail. When choosing the Navigate to New Dashboard State action type, the user will be transferred to the previously created state of your choice.

Assuming that the user has already added a new state to the dashboard and is familiarized with the” Add action” “step, we will proceed directly to the action configuration step.

• Enter edit widget mode and open “Add action” window

• As an example, select “Widget header button” as action source

• Input a name for the action and select an icon that will represent a button. With this icon, an action will be performed

• Select the “Navigate to new dashboard state” action type from the “Action” drop-down menu

• After choosing an action type, the “Target dashboard state” drop-down menu appears. Select a previously created state you would like to be transitioned to

• When the desired state has been selected, click the “Add” button at the bottom of the “Add action” window

• In the “Actions” window, user can see the configured action, so user can verify the action source, icon, and action type. Click “Save”, and then click “Apply” to save the widget settings.

• Save the dashboard by clicking “Save” in the upper right corner of the dashboard page. After saving the changes, an action icon is available next to configured widget.

• Clicking on that will be transferred to the state specified in the action.

Open new dashboard state in a separate dialog or in a popup window

There are times when it doesn’t make sense to move to a separate dashboard state to view the details of a widget, and the user just wants to open it on the same dashboard page. For these situations, there is a Dashboard state display option feature that allows opening another state on the same page in a separate dialog box or in a popup window.

In the action settings, select the desired dashboard state display option and make additional window settings such as show/hide dashboard toolbar, popup window width and height, etc.

As an example, consider displaying the new dashboard state in a separate dialog window:

• Select a “Open in separate dialog” option in the “Dashboard state display option” field

• By default, the checkbox “Hide dashboard toolbar in dialog” is selected. If the user needs to see a toolbar in the dialog window, uncheck it. The toolbar displays entities, time window, dashboard export button, and expand to a fullscreen button

• It is optional to adjust a dialog width and height in percents. Width is relative to viewport height, and height is relative to width correspondingly.

• When the action has been configured, save all changes.

Clicking on action icon in the widgets, opens a dialog window with the new state.

Update Current Dashboard State

This action type allows updating a dashboard that user is currently on. While using a dashboard, user can view detailed information about a specific device/asset in real-time. The most common use of this action type is through Chart widgets where user can see the details more accurately.

Enter Edit Mode of the dashboard and click the "Add new widget" button at the top of the screen
Find the "Charts" widget bundle and click on it
Select the "Time series chart" widget
Navigate to the "Entity Alias" tab in the "Datasource" section. Enter the desirable alias name in the "Entity alias" field and click the "Create a new one!" button
Select the "Entity from Dashboard State" from the "Filter type" field and click "Add"
Replace the label of the "temperature" key with ${entityName}. Then, click "Add" to add new widget on the dashboard
Drag the "Time series chart" widget to a free space and resize it

Follow the below steps to add action to the widget

Enter edit widget mode and open “Add action” window
Select the “Widget header button” action source
Input a name for the action and select an icon that will represent a button. With this icon, the action will be performed
Select the “Update Current Dashboard State” action type from the “Action” drop-down menu
Click the “Add” button at the bottom of the “Add action” window
Now in the “Actions” window the user can see the configured action, verify the action source, icon, and action type. Click “Save”, then click “Apply” to save the widget settings.
Save the dashboard by clicking “Save” in the upper right corner of the dashboard page

Navigate to Other Dashboard

This type of action is used to navigate between the dashboards.

Enter "Edit Widget Mode" and open “Add action” window
As an example for this manual, select “Widget Header button” action source
Input a name for the action and select an icon that will represent a button. With this icon, the action will be performed
Select the “Navigate to Other Dashboard” action type from the “Action” drop-down menu
After choosing an action type, the “Target Dashboard State” drop-down menu appears. Select a dashboard user to be transitioned to. Note that the user can also navigate to an existing state of the selected dashboard
When the desired dashboard has been selected, click the “Add” button at the bottom of the “Add action” window

In the “Actions” window, the user can see the configured action, verify the action source, icon, and action type. Click “Save”, and then click “Apply” to save the widget settings
Save the dashboard by clicking “Save” in the upper right corner of the dashboard page.

NOTE: After saving the changes, an icon will appear in the upper right part of the widget.

Clicking this icon will be transferred to the previously selected dashboard (or chosen state in that dashboard)

Action Sources

Action Sources are specific actions that need to be performed to achieve a goal. They vary across different widgets.

Action Cell Button

The “Action Cell Button” source adds an action button to each individual entity in the widget.

For example, let’s consider the use of the “Action Cell Button”. Clicking on the action icon of a selected entry in the Time Series Table will transfer us to another state.

Enter "Edit Widget Mode" and open the “Add action” window
Select the “Action Cell Button” action source
Input a name for the action and select an icon that will represent a button. With this icon, the action will be performed
Select a “Navigate to New Dashboard State” action type from the “Action” drop-down menu;
After choosing an action type, the “Target Dashboard State” drop-down menu appears. Select a previously created state user to be transitioned to
When the desired state has been selected, click the “Add” button at the bottom of the “Add action” window
In the “Actions” window, the user can see the configured action, verify the action source, icon, and action type. Click “Save”, then click “Apply” to save the widget settings
Save the dashboard by clicking “Save” in the upper right corner of the dashboard page

There should be an action cell button next to each row in the table. By clicking this button, the corresponding action will be executed, namely transitioning to the chosen state.

Widget Header Button

The “Widget Header Button” source adds an action button in the header of the widget. Clicking this button execute an action. This button is responsible for the whole widget, not for separate entities. The Widget Header Button is the most commonly used action source, and it can be found in all widgets. To configure the Widget Header Button action source, follow the these steps:

Enter "Edit Widget Mode" and open the “Add action” window
Select the “Widget Header Button” action source
Input a name for the action and select an icon that will represent a button. With this icon, the action will be performed
Select the “Navigate to New DashboardState” action type from the “Action” drop-down menu
After choosing an action type, the “Target Dashboard State” drop-down menu appears. Select a previously created state user to be transitioned to
When the desired state has been selected, click the “Add” button at the bottom of the “Add action” window
In the “Actions” window, the user can see the configured action, verify the action source, icon, and action type. Click “Save”, then click “Apply” to save the widget settings.
Save the dashboard by clicking “Save” in the upper right corner of the dashboard page

An action button should appear in the header of the widget. After you click it, the action will be performed, namely, the transition to the chosen state.

On Row Click

The “On Row Click” source triggers an action when a row in the widget is clicked.

For example, let’s illustrate the use of the “On row click” action with the aforementioned widget. Clicking on a row of the selected Alarm in the widget will navigate us to another state.

Enter "Edit Widget Mode" and open the “Add action” window
Select the “On Row Click” action source
Input a name for the action. Select an icon
Select a “Navigate to New Dashboard State” action type from the “Action” drop-down menu
After choosing an action type, the “Target Dashboard State” drop-down menu appears. Select a previously created state user to be transitioned to
When the desired state has been selected, click the “Add” button at the bottom of the “Add action” window
Now in the “Actions” window, the user can see the configured action, verify the action source, icon, and action type. Click “Save”, then click “Apply” to save the widget settings
Save the dashboard by clicking “Save” in the upper right corner of the dashboard page

Click on any Alarm row to perform an action, namely, to navigate to the selected state where detailed information about the chosen device is displayed.

On HTML Element Click (only in HTML widgets)

The HTML widgets allow full configuration by customizing an HTML code in their settings. To add an action to these widgets, the user needs to add an action identifier to the written code. Clicking on an item in the widget will then execute the configured action.

For example adding an HTML Card widget to the dashboard. Clicking anywhere on the widget will perform the action.

Enter "Edit Widget Mode" and open “Add action” window
Click the “Add widget” button at the top of the screen or click the large “Add new widget” icon in the center of the screen
Find the “HTML Widgets” bundle and click on it
Select the “HTML Card” widget
Navigate to the “Actions” tab. Click the “plus” icon in the top right corner of the screen to open a new “Add action” window
Input a name for the action
Select the “On HTML Element Click” source
Select the “Navigate to New Dashboard State” action type from the “Action” drop-down menu
After choosing an action type, the “Target Dashboard State” drop-down menu appears. Select a previously created state user to be transitioned to
When the desired state has been selected, click the “Add” button at the bottom of the “Add action” window
• Navigate to the “Appearance” tab of the widget; CSS and HTML fields are available here
In the HTML section, enter the action’s ID which should be its name in a specific format
- <div id='state' class='card'>Devices location</div>
  
  where “state” is the name of the action and “Dashboard state” is the text that is going to be shown on the HTML Card widget

Click the “Add” button

Save the dashboard by clicking “Save” in the upper right corner of the dashboard page. To execute an action click anywhere on the widget.

Map Widget Action Sources

The Map Widget has unique action sources that need to be considered separately.

Add a map widget, namely OpenStreetMap widget. Refer to how to create and configure a map widget.

On Circle Click

Circle is a plane figure, of which boundary points are always the same distance away from a fixed central point. We use a circle that is based on coordinates that are specified within the device we use.

Circle coordinates are being received in a format:

{"latitude": 37.770460000, "longitude":-122.510870000, "radius":700}

Enter "Edit Widget Mode" and open the “Add action” window
Select the “On Circle Click” action source
Input a name for the action. Select an icon
Select the “Navigate to New Dashboard State” action type from the “Action” drop-down menu
After choosing an action type, the “Target Dashboard State” drop-down menu appears. Select a previously created state user to be transitioned to

When the desired state has been selected, click the “Add” button at the bottom of the “Add action” window
In the “Actions” window, the user can see the configured action, verify the action source, icon, and action type. Click “Save”, then click “Apply” to save the widget settings
Save the dashboard by clicking “Save” in the upper right corner of the dashboard page

Click on the circle on the map

The action will be performed, namely, the transition to the specified state.

On Marker Click

The action will be executed by clicking on the red entity marker on the map.

Enter "Edit Widget Mode" and open “Add action” window
Select the “On Marker Click” action source
Input a name for the action. Select an icon
Select the “Navigate to New Dashboard State” action type from the “Action” drop-down menu
After choosing an action type, the “Target Dashboard State” drop-down menu appears. Select a previously created state user to be transitioned to

When the desired state has been selected, click the “Add” button at the bottom of the “Add action” window
In the “Actions” window, the user can see the configured action, verify the action source, icon, and action type. Click “Save”, then click “Apply” to save the widget settings
Save the dashboard by clicking “Save” in the upper right corner of the dashboard page

Click on the marker on the map

The configured action “Navigate to New Dashboard state will be performed

Marker Placement

In Marker Placement, navigate to different dashboards from the On Marker Click Action Source, by configuring multiple actions with action source “On marker click.”

In the Widget Action section, add a new action with the source as “On marker click,” assign it a meaningful Name for the action, and in the Type field select “Navigate to other dashboard.” In the Target dashboard field, select the dashboard to navigate to. The Marker entity dropdown list will populate with all the entities available. Select the desired entity and click Save.

Note: To list all the available entities in the “Marker entity” field, add the widget and reopen it to configure the action.

On Polygon Click

The Polygon is a plane figure that is described by a finite number of dots. A polygon is based on coordinates specified within the device, the user may mark their assets and any other entities with a polygon option.

Polygon coordinates are being received in a format:

[[1CoordinateLatitude,1CoordinateLatitude],[2CoordinateLatitude,2CoordinateLatitude]...[nCoordinateLatitude,nCoordinateLatitude]]

where n - number of coordinates which polygon is described by.

Enter "Edit Widget Mode" and open “Add action” window
Select the “On Polygon Click” source
Input a name for the action. Select an icon
Select the “Navigate to New Dashboard State” action type from the “Action” drop-down menu
After choosing an action type, the “Target Dashboard State” drop-down menu appears. Select a previously created state user to be transitioned to
When the desired state has been selected, click the “Add” button at the bottom of the “Add action” window
In the “Actions” window, the user can see the configured action, verify the action source, icon, and action type. Click “Save”, then click “Apply” to save the widget settings
Save the dashboard by clicking “Save” in the upper right corner of the dashboard page

Tooltip Tag Action

Map Widget settings can be configured in such a way that when the user clicks on a marker, a tooltip appears. The tooltip can contain a link that will execute the configured action.

NOTE: This manual explains only the basic usage of the tooltip tag action source. It is possible to configure several links for various devices/assets that return different values. Use the tooltip function in the advanced mode of the map widget to accomplish this.

Enter "Edit Widget Mode" and open the “Add action” window
Select the “Tooltip Tag Action” source
Input a name for the action. Select an icon
Select the “Navigate to New Dashboard State” action type from the “Action” drop-down menu
After choosing an action type, the “Target Dashboard State” drop-down menu appears. Select a previously created state user to be transitioned to
When the desired state has been selected, click the “Add” button at the bottom of the “Add action” window
In the “Actions” window, you can see the configured action; user can double-check the action source, icon, and action type
•Navigate to the “Appearance” tab of the widget
Scroll down to the Tooltip Configuration and toggle the “Show tooltip” checkbox
In the Tooltip line find the link-act name and input an ID of the action that is its name in this format:
- <link-act name='TooltipTag'>Navigate to the ${entityName}</link-act>
  
  where TooltipTag is an action name and Navigate to is the text that will be shown as a link on a tooltip.

Click “Apply” to save the widget settings
Save the dashboard by clicking “Save” in the upper right corner of the dashboard page

Click on the marker on the map to display the tooltip. To perform the action, click on the link text at the bottom of the tooltip.

Special Actions Settings

Open right dashboard layout (mobile view)

Often, users need to see updated information about an entity from one widget to another widget next to it. For example, we have a list of assets in the “Entity Table” widget, and we want to see their details in the “Time Series Chart” widget next to it. On the desktop, this is easy to set up by placing the two widgets side by side and selecting the action type “Update Current Dashboard””. However, on the responsive screen of a mobile device, the widgets are automatically stacked one below the other. This means that you’ll need to scroll down to view the relevant information on the second widget.

The Layouts feature solves this issue. To configure layouts follow these steps:

Enter the Dashboard's "Edit Mode" on the top left of the window, click the "Manage Layouts" icon
In the opened "Manage Layouts" window, turn the "Divider" option to 'on'
Now we have two layouts. Optionally, the user can adjust the size of the windows in a certain percentage ratio relative to each other. Click "Save"