This widget displays a box with the last available value of a metric or a statistic.
For instance, you can display the current value of a temperature metric.
Layouts
Within a gauge, you can change the background color, and icon, choosing between a Font Awesome icon or, a static icon published to an HTTP address.
In the alternative, you can change also the box layout, choosing between:
| Small Box | Info Box |
 |
|
Metric Data Aggregation
In addition to showing the current metric value, the gauge can aggregate values, also on multiple things and within a time period.
For instance, within a location details page, you can display the total number of pieces produced by the machine, under the location, for a certain period.
The supported aggregations are:
- AVG: Displays the average value which can be relative in case a period has been defined or absolute considering all the available data. In the case of multiple things, the average is computed among all things.
- DELTA: Displays the variation of a metric within a period. In the case of multiple things, the resulting deltas are summed up. In case the period is not defined, the delta is computed over all the available data.
- DELTA_AVG_DAYS_1: Displays the average of the daily deltas in a period. In the case of multiple things, the daily deltas are summed up by day. In case the period is not defined, the average is computed over all the daily deltas.
- MIN: Displays the minimum value which can be relative in case a period has been defined or absolute considering all the available data. In the case of multiple things, the minimum is computed among all things.
- MAX: Displays the maximum value which can be relative in case a period has been defined or absolute considering all the available data. In the case of multiple things, the maximum is computed among all things.
Value Comparison
You can use the gauge to display the value increment with respect to the previous value.
In input to the gauge, it is possible to provide a dynamic period, by using a page period field, or a static period hardcoded into the template (e.g. THIS_MONTH). When the value increment is enabled, the gauge computes the value for the previous period and displays the increment.
The increment can be displayed as a percentage or as an absolute value. Moreover, within the same box, you can also display the value relative to the previous period.
The following gauge displays the consumption of energy during this month (DELTA over the Energy metric), the consumption of the previous month, the absolute increment, and the relative percentage.
Here is the same gauge with a different layout
The increment can be displayed differently depending on whether it is a negative or a positive thing.
Previous period calculation logic
Based on the input period, the gauge calculates the comparison period according to this logic.
If the input period is open at the end (not yet concluded), such as TODAY, THIS_MONTH, THIS_YEAR, the comparison period takes into account the end date, for instance:
- Input Period: 01 September 2022 - 19 September 2022
- Comparison Period: 01 August 2022 - 19 August 2022
If the period identifies a whole day, month or year, the comparison considers the previous day, month, or year. In all other cases, the previous period is the input period reversed in the past, for instance:
- Input Period: 10 September 2022 - 20 September 2022
- Comparison Period: 01 September 2022 - 10 September 2022
Design View
In the visual editor, you can find the Gauge icon 
You can drag and drop the widget in the grid, and then according to your needs configure the following sub-elements:
Code View
Template Syntax
Below you can find some examples of how to use the component within a template.
Example 1
Gauge displaying the current value of running hours.
<gauge-widget iconName="fa-clock-o">
<metric name="Running Hours" filter="millisToHours"></metric>
</gauge-widget>
Example 2
Gauge displaying the number of pieces produced in a selected period from a set of things.
<period-field></period-field>
<things-filter-field id="machinesFilter"></things-filter-field>
<gauge-widget aggregation="DELTA"
periodRef="period"
queryFieldRef="machinesFilter"
showIncrement="RELATIVE">
<metric name="thing.Total Pieces"></metric>
</gauge-widget>
Component Reference
Here is a comprehensive list of all the elements and properties that can be used to configure the component.
| Gauge <gauge-widget> | |
|---|---|
| PROPERTIES | |
| Aggregation | Indicates whether to render the last value or the aggregated value.
Type: ENUM | Optional | Values: LAST_VALUE AVG DELTA DELTA_AVG_DAYS_1 MIN MAX aggregation="AVG" |
| Background Color Class | The class applied on the background, refer to the Bootstrap Colors guide
Type: STRING | Optional backgroundColorClass="fooBar" |
| CSS Class | The name(s) of the CSS class used to customize the widget layout.
Type: STRING | Optional class="my-custom-class" |
| End Date Variable | The <period-field>'s End Variable filtering data by end date.
Type: STRING | Optional endDateFieldRef="toDate" [DEPRECATED] Use the Period Variable property instead. |
| Icon Name | The name of the Font Awesome icon.
Type: STRING | Optional iconName="fa-thermometer" |
| Icon Url | The URL where the icon to display is located.
Type: STRING | Optional iconUrl="fooBar" |
| Increment Value Position | Indicates whether to place the increment value
Type: ENUM | Optional | Values: RIGHT BOTTOM incrementValuePosition="BOTTOM" |
| Layout | Indicates the rendering layout
Type: ENUM | Optional | Values: INFO_BOX SMALL_BOX layout="SMALL_BOX" |
| Measure Unit Position | Indicates where to place the unit of measurement.
Type: ENUM | Optional | Values: NONE METRIC_NAME_RIGHT METRIC_VALUE_RIGHT measureUnitPosition="METRIC_NAME_RIGHT" |
| Null Increase Class | The CSS class customizing how to render a null variation (e.g. text-gray) when the increment value si displayed.
Type: STRING | Optional nullIncreaseClass="fooBar" |
| Period | The default period to use when computing DELTA.
Type: ENUM | Optional | Values: LAST_24H LAST_7_DAYS LAST_30_DAYS THIS_MONTH THIS_YEAR period="LAST_7_DAYS" |
| Period Variable | The id of the page's variable providing the date range filtering period, for instance the id of a <period-filter-field>.
Type: STRING | Optional periodRef="period" |
| Query Variable | The id of the page's <things-filter-field> used for searching.
Type: STRING | Optional queryFieldRef="query-1" |
| Show Increment | Indicates whether the increment value should be calculated from the previous time period.
Type: ENUM | Optional | Values: NONE ABSOLUTE PERCENTAGE ABSOLUTE_AND_PERCENTAGE showIncrement="ABSOLUTE" |
| Show Last Update | The flag indicating whether to show or hide the last update timestamp.
Type: BOOLEAN | Optional | Values: true false [showLastUpdate]="true" |
| Show Previous Value | Indicates whether the previous value must be displayed on the right of the current one.
Type: BOOLEAN | Optional | Values: true false [showPreviousValue]="true" |
| Start Date Variable | The <period-field>'s Start Variable filtering data by start date.
Type: STRING | Optional startDateFieldRef="fromDate" [DEPRECATED] Use the Period Variable property instead. |
| Title | The title displayed on the top part of the widget box.
Type: STRING | Optional [title]="'Details'" |
| Value Decrease Class | The CSS class customizing how to render a negative variation (e.g. text-red) when the increment value si displayed.
Type: STRING | Optional valueDecreaseClass="fooBar" |
| Value Increase Class | The CSS class customizing how to render a positive variation (e.g. text-green) when the increment value si displayed.
Type: STRING | Optional valueIncreaseClass="fooBar" |
| Visibility Condition | The expression that allows you to reduce the visibility of the element.
Type: STRING | Optional *ngIf="getUser().organizationId != null" |
| SUB-ELEMENTS | |
| Metric | The metric whose current value must be displayed within the gauge box. single | mandatory <metric name="Temperature"></metric> |
| Statistic | The statistic whose value must be displayed within the gauge box. single | mandatory <statistic name="alertCount"></statistic> |
| Composite Part | The widget part combining multiple properties and metrics. multiple | optional <composite-part> <metric name="Temperature"></metric> <metric name="Humidity"></metric> <property name="properties.type"></property> </composite-part> |
| Metric <metric> | |
|---|---|
| PROPERTIES | |
| Filter | The name of the filter used to transform and display values.
Type: FILTER | Optional filter="fooBarFilter" |
| Label | The metric alternative label.
Type: STRING | Optional label="Temperature" |
| Name | The metric whose value(s) must be loaded by the widget.
Type: METRIC | Mandatory name="Temperature" |
| Unit | The unit of measurement to be displayed along the value.
Type: STRING | Optional unit="°C" |
| Visibility Condition | The expression that allows you to reduce the visibility of the element.
Type: STRING | Optional *ngIf="getUser().organizationId != null" |
| Statistic <statistic> | |
|---|---|
| PROPERTIES | |
| Aggregated Property | The property aggregate when using the Property Aggregation statistic.
Type: PROPERTY | Optional property="serialNumber" |
| Aggregation | The aggregation used to retrieve metric data.
Type: ENUM | Optional | Values: SUM MIN MAX AVG DELTA aggregation="MAX" |
| Alert Category | The alert category used to filter the statistic results.
Type: ENUM_ARRAY | Optional | Values: INFORMATION ADVICE ANOMALY FAILURE SAFETY [category]="['ANOMALY', 'FAILURE']" |
| Alert Severity | The alert severity used to filter the statistic results.
Type: ENUM_ARRAY | Optional | Values: INFORMATIONAL WARNING CRITICAL EMERGENCY [severity]="['WARNING', 'CRITICAL']" |
| End Date Variable | The <period-field>'s End Variable filtering data by end date.
Type: STRING | Optional endDateFieldRef="toDate" [DEPRECATED] Use the Period Variable property instead. |
| Filter | The name of the filter used to transform and display values.
Type: FILTER | Optional filter="fooBarFilter" |
| Group By | The properties names used to group statistic results.
For instance: ['customer.country', 'location.properties.city'].
In the case where the underlying objects are temporally distributed you can also aggregate by HOUR, DAY, MONTH and YEAR.
Type: JSON | Optional [groupBy]="['MONTH', 'name']" |
| Include Zero Values | The flag indicating whether to include or not the alerts with zero occurrences.
Type: BOOLEAN | Optional | Values: true false [includeZeroValues]="true" |
| Max Result Count | The number of returned results (default all results are returned).
Type: INTEGER | Optional [limit]="123" |
| Name | The statistic whose results(s) must be loaded by the widget.
Type: STATISTIC | Mandatory | Values: activeAlertCount activatedAlertCount alertCount alertCountByAlertDefinition thingCount thingPropertyAggregation locationCount customerCount userCount workSessionCount workSessionCount workSessionElapsedTime workSessionSumMetricValues name="alertCount" |
| Period Variable | The id of the page's variable providing the date range filtering period, for instance the id of a <period-filter-field>.
Type: STRING | Optional periodRef="period" |
| Query | The array of conditions filtering out items.
For instance: [query]='[{'property': 'connectionStatus', 'predicate': 'eq', 'value': '1'}]'
Predicates: eq, beginsWith, like, notLike, isEmpty, isNotEmpty, gt, gte, lt, lte.
Type: JSON | Optional [query]="[{'property': 'connectionStatus', 'predicate': 'eq', 'value': '1'}, {...}]" |
| Start Date Variable | The <period-field>'s Start Variable filtering data by start date.
Type: STRING | Optional startDateFieldRef="fromDate" [DEPRECATED] Use the Period Variable property instead. |
| Sum Metric | The work-session monitored metric to sum.
Type: STRING | Optional sumMetric="metrics.Pieces.DELTA" |
| Thing Definition | The name of the thing-definition used to filter the statistic results.
Type: STRING | Optional thingDefinition="fooBar" |
| Composite Part <composite-part> | |||||
|---|---|---|---|---|---|
| PROPERTIES | |||||
| Filter | The filter applied on the composite-part to transform or display its value.
Type: FILTER | Optional filter="fooBarFilter" |
||||
| Label | The label displayed by the widget.
Type: STRING | Optional label="fooBar" |
||||
| Name | The composite-part name.
Type: STRING | Optional name="fooBar" |
||||
| Visibility Condition | The expression that allows you to reduce the visibility of the element.
Type: STRING | Optional *ngIf="getUser().organizationId != null" |
||||
| SUB-ELEMENTS | |||||
| Metric | The metric whose value must be loaded within the composite-part. multiple | optional <metric name="Temperature"></metric>
|
||||
| Property | The property whose value must be loaded within the composite-part. multiple | optional <property name="serialNumber"></property>
|
||||
Comments
0 comments
Please sign in to leave a comment.