Loading
Real-time Gauges
The linear gauge is a real-time chart, which can continuously request new data from the server and display the same, without involving any page refreshes. The chart initializes itself, loads new data every n seconds, and silently updates itself to reflect the current state of data. There are two different ways to update the linear gauge; one method directly polls data from the server while the other retrieves data using JavaScript API methods.
In this section, you will be shown how you can:
-
Configure real-time updates using JavaScript API
-
Configure real-time updates using server-side script
-
Stop and restart updates
-
Configure events associated with real-time gauges
-
Troubleshoot real-time gauges
Configuring Real-time Updates using JavaScript API
Real-time Data Format
The real-time data format for linear gauge depends on:
-
Whether you’ve multiple pointers on the chart or a single pointer?
-
If you’ve multiple pointers, whether you want to provide data by pointer numerical index or by their defined IDs?
-
Whether you’re using Message Logger for the chart?
-
Commands for the chart - like stop update
Simple Example
Updating a Single Pointer
In the simplest form, if you’re looking to update the value of a gauge, you need to output the data in following format:
Here, the output is a single value, 75. So, when the gauge will read this value, it will update the chart by setting its value to 75 (if a data range is provided by the gauge, the value will first be checked to verify if it falls within the defined range).
A linear gauge configured to update the value of a single pointer looks like this:
Given below is a brief description of the JavaScript API methods used to configure real-time updates:
| Function Name | Parameter | Description |
|---|---|---|
|
strData |
This method feeds real-time data to the gauge using JavaScript. The data has to be in the same format as provided by the real-time data provider page. |
The data structure needed to configure real-time updates using JavaScript API is given below:
{
"chart": {
"theme": "fint",
"caption": "Server CPU Utilization",
"lowerLimit": "0",
"upperLimit": "100",
"numberSuffix": "%",
"chartBottomMargin": "20",
"valueFontSize": "11",
"valueFontBold": "0",
"gaugeFillMix": "{light-10},{light-70},{dark-10}",
"gaugeFillRatio": "40,20,40"
},
"colorRange": {
"color": [
{
"minValue": "0",
"maxValue": "35",
"label": "Low"
},
{
"minValue": "35",
"maxValue": "70",
"label": "Moderate"
},
{
"minValue": "70",
"maxValue": "100",
"label": "High"
}
]
},
"pointers": {
"pointer": [
{
"value": "75"
}
]
}
}Updating Multiple Pointers
If you have multiple pointers defined, you can update them all in a single update as shown in the following output from the real-time data provider page:
Here, we are specifying two values in the real-time update. So, assuming that we have two pointers defined for the gauge , each one of them will take the values in sequence and update itself. Therefore, the first pointer will now show 34 and second one will show 25. The sequence of the pointers is determined by the order in which they are defined in the JSON/XML data.
A linear gauge configured to update multiple pointers looks like this:
The data structure needed to update multiple pointers is given below:
{
"chart": {
"theme": "fint",
"caption": "Server CPU Utilization",
"subcaption": "Transaction Server vs Web Server",
"subcaptionFontBold": "0",
"subCaptionFontSize": "12",
"lowerLimit": "0",
"upperLimit": "100",
"numberSuffix": "%",
"valueAbovePointer": "1",
"chartBottomMargin": "20",
"valueFontSize": "11",
"valueFontBold": "0",
"gaugeFillMix": "{light-10},{light-70},{dark-10}",
"gaugeFillRatio": "40,20,40"
},
"colorRange": {
"color": [
{
"minValue": "0",
"maxValue": "35",
"label": "Low",
"code": "#6baa01"
},
{
"minValue": "35",
"maxValue": "70",
"label": "Moderate",
"code": "#f8bd19"
},
{
"minValue": "70",
"maxValue": "100",
"label": "High",
"code": "#e44a00"
}
]
},
"pointers": {
"pointer": [
{
"value": "75",
"bgColor": "#999999",
"bgAlpha": "80",
"tooltext": "Transaction Server: $value%"
},
{
"value": "92",
"bgColor": "#444444",
"bgAlpha": "80",
"tooltext": "Web Server: $value%"
}
]
}
}Updating Pointer(s) using the Named ID
Another way to update pointers is by defining a unique ID for each pointer and then passing the updated data value to the ID.
To define unique IDs for pointers, you can use the code snippet shown below:
"pointers": {
"pointer": [
{
...
"id": "gGrovePointer",
...
},
{
...
"id": "bFieldPointer",
...
}
]
}You can now update each of these named pointers as shown in the following output in your real-time data stream:
This will change the value of pointer 1 (having the id gGrovePointer) to 65 and pointer 2 (having the id bFieldPointer) to 80.
A linear gauge configured to update the values of multiple pointers using named IDs looks like this:
Given below is a brief description of the JavaScript API methods used to update pointers using their IDs:
| Function Name | Parameter | Description |
|---|---|---|
|
strData |
This method feeds real-time data to the gauge using JavaScript. The data has to be in the same format as provided by the real-time data provider page. |
|
pointerIndex |
This method returns the data for the given pointer index on the chart. The first pointer is represented by index 1, second by 2, and so on. |
|
pointerId |
This method returns the data for the given pointer using its defined ID. |
|
pointerIndex, value |
This method sets the data for the given pointer index on the chart. The first pointer is represented by index 1, second by 2 and so on. |
|
pointerId, value |
This method returns the data for the given pointer using its defined ID. |
The data structure needed to update pointers using IDs is given below:
{
"chart": {
"theme": "fint",
"caption": "Server CPU Utilization",
"subcaption": "Transaction Server vs Web Server",
"subcaptionFontBold": "0",
"subCaptionFontSize": "12",
"lowerLimit": "0",
"upperLimit": "100",
"numberSuffix": "%",
"valueAbovePointer": "0",
"chartBottomMargin": "20",
"valueFontSize": "11",
"valueFontBold": "0",
"gaugeFillMix": "{light-10},{light-70},{dark-10}",
"gaugeFillRatio": "40,20,40"
},
"colorRange": {
"color": [
{
"minValue": "0",
"maxValue": "35",
"label": "Low",
"code": "#6baa01"
},
{
"minValue": "35",
"maxValue": "70",
"label": "Moderate",
"code": "#f8bd19"
},
{
"minValue": "70",
"maxValue": "100",
"label": "High",
"code": "#e44a00"
}
]
},
"pointers": {
"pointer": [
{
"id": "transServer",
"value": "75",
"bgColor": "#999999",
"bgAlpha": "80",
"tooltext": "Transaction Server: $value%"
},
{
"id": "webServer",
"value": "92",
"bgColor": "#444444",
"bgAlpha": "80",
"tooltext": "Web Server: $value%"
}
]
}
}You can call the JavaScript APIs of a chart only after it has rendered. You can use the FC_Rendered event tracker or the Rendered event listener to check if a chart has rendered.
Retrieving Data from the Gauge
We can retrieve data from gauge once the data has been updated.
A linear gauge configured to retrieve updated data looks like this:
The data structure needed to retrieve updated data is as follows:
{
"chart": {
"theme": "fint",
"caption": "Server CPU Utilization",
"lowerLimit": "0",
"upperLimit": "100",
"numberSuffix": "%",
"chartBottomMargin": "20",
"valueFontSize": "11",
"valueFontBold": "0",
"gaugeFillMix": "{light-10},{light-70},{dark-10}",
"gaugeFillRatio": "40,20,40"
},
"colorRange": {
"color": [
{
"minValue": "0",
"maxValue": "35",
"label": "Low"
},
{
"minValue": "35",
"maxValue": "70",
"label": "Moderate"
},
{
"minValue": "70",
"maxValue": "100",
"label": "High"
}
]
},
"pointers": {
"pointer": [
{
"value": "75"
}
]
}
}Real-time Updates using Server-side Script
An LED gauge updated in real-time using a server-side script looks like this:
Given below is a brief description of the attributes used to configure real-time updates using server-side scripts:
| Attribute Name | Description |
|---|---|
|
This parameter sets the path of the page which is supposed to relay real-time data to the chart. If you have special characters as a part of the data stream URL, like ? or &, you will have to URL Encode the entire |
|
For this parameter, we can specify the number of seconds after which the chart will look for new data. This process will happen continuously - i.e., if we specify 5 seconds here, the chart will look for new data after every 5 seconds. |
|
Constantly changing data stamp that can be added to the real-time data URL, so as to maintain a state. For more information, read the tutorials/advanced-charting/real-time-charts/adding-data-stamp.md article. |
The data structure needed to to configure real-time updates using server-side script is given below:
{
"chart": {
"theme": "fint",
"caption": "Server CPU Utilization",
"subcaption": "food.hsm.com",
"lowerLimit": "0",
"upperLimit": "100",
"numberSuffix": "%",
"chartBottomMargin": "40",
"valueFontSize": "11",
"valueFontBold": "0",
"dataStreamUrl": "resources/php/gauge-and-widgets-guide-linear-gauge-real-time-gauges-php-1.php",
"refreshInterval": "10"
},
"colorRange": {
"color": [
{
"minValue": "0",
"maxValue": "35",
"label": "Low",
"code": "#6baa01"
},
{
"minValue": "35",
"maxValue": "70",
"label": "Moderate",
"code": "#f8bd19"
},
{
"minValue": "70",
"maxValue": "100",
"label": "High",
"code": "#e44a00"
}
]
},
"pointers": {
"pointer": [
{
"value": "75"
}
]
}
}Stopping/Restarting Updates
An LED gauge configured to stop and restart receiving real-time updates looks like this:
Given below is a brief description of the JavaScript API used to stop and restart receiving real-time updates:
| Function Name | Parameter | Description |
|---|---|---|
|
|
This method is used to stop the gauge from self-updating. |
|
|
If you have stopped the gauge from updating itself in real-time, this method is used to restart the updates. |
The data structure needed to stop and restart receiving real-time updates is given below:
{
"chart": {
"theme": "fint",
"caption": "Server CPU Utilization",
"subcaption": "food.hsm.com",
"lowerLimit": "0",
"upperLimit": "100",
"numberSuffix": "%",
"chartBottomMargin": "40",
"valueFontSize": "11",
"valueFontBold": "0",
"dataStreamUrl": "resources/php/gauge-and-widgets-guide-linear-gauge-real-time-gauges-php-2.php",
"refreshInterval": "10"
},
"colorRange": {
"color": [
{
"minValue": "0",
"maxValue": "35",
"label": "Low",
"code": "#6baa01"
},
{
"minValue": "35",
"maxValue": "70",
"label": "Moderate",
"code": "#f8bd19"
},
{
"minValue": "70",
"maxValue": "100",
"label": "High",
"code": "#e44a00"
}
]
},
"pointers": {
"pointer": [
{
"value": "75"
}
]
}
}Configuring Real-time Events
FusionCharts Suite XT introduces two events, realTimeUpdateComplete and realTimeUpdateError, to track real-time updates on gauges.
A real-time linear gauge configured to listen to the realTimeUpdateComplete event looks like this:
Given below is a brief description of the realTimeUpdateComplete event:
| Event Name | Description |
|---|---|
|
This event is raised every time the real-time gauge updates itself with new data. This event is raised in any of the following cases: |
|
This event is raised when an error occurs while performing real-time update using |
The data structure needed to configure the realTimeUpdateComplete event for real-time angular gauge is given below:
{
"chart": {
"theme": "fint",
"caption": "Server CPU Utilization",
"lowerLimit": "0",
"upperLimit": "100",
"numberSuffix": "%",
"chartBottomMargin": "40",
"valueFontSize": "11",
"valueFontBold": "0",
"showValue": "0",
"gaugeFillMix": "{light-10},{light-70},{dark-10}",
"gaugeFillRatio": "40,20,40"
},
"colorRange": {
"color": [
{
"minValue": "0",
"maxValue": "35",
"label": "Low"
},
{
"minValue": "35",
"maxValue": "70",
"label": "Moderate"
},
{
"minValue": "70",
"maxValue": "100",
"label": "High"
}
]
},
"pointers": {
"pointer": [
{
"value": "75"
}
]
},
"annotations": {
"origw": "400",
"origh": "190",
"autoscale": "1",
"groups": [
{
"id": "range",
"items": [
{
"id": "rangeBg",
"type": "rectangle",
"x": "$chartCenterX-70",
"y": "$chartEndY-35",
"tox": "$chartCenterX +70",
"toy": "$chartEndY-15",
"fillcolor": "#ff6650"
},
{
"id": "rangeText",
"type": "Text",
"fontSize": "11",
"fillcolor": "#000000",
"text": "Currently Utilizing 75%",
"x": "$chartCenterX",
"y": "$chartEndY-25"
}
]
}
]
}
}Troubleshooting
While accessing any of the JavaScript methods listed above, if you get an error like “… is not a function of …”,
-
Make sure that you are not calling the JavaScript method before the chart has loaded and rendered. You need to use the
FC_Renderedfunction or define the event listener for theRenderedevent of the chart to track the loading of chart as explained in the FusionWidgets XT and JavaScript section. -
Make sure that you are NOT running the chart from local file system (C:\ , D:\). Instead, run the chart from behind a server (localhost - IIS, Apache etc.). This is because the default security settings do not allow JavaScript interactions on local file system, unless otherwise specifically set.
There! You have now seen how you can work with and troubleshoot real-time linear gauges.