Demos

Beginner's Guide

Charts / Gauges / Maps Guide

Customizing Charts

API

Integrating With Your Stack

Help

The gauges in the FusionCharts Suite XT are real-time gauges that can continuously request and render new data without involving a page refresh. The gauges achieve this functionality in two ways:

  • Using JavaScript API

  • Using server-side scripts

In this section, you will be shown how you can:

Configuring Real-time Updates using JavaScript API

Real-time Data Format

The real-time data format for gauges depends on the data value to be passed.

In the simplest form, if you’re looking to update the cylinder gauge, you need to pass a single value to the value attribute using the JSON key-value pair format. If this data is within the acceptable range of the chart, the chart will be updated to depict this value.

However, to dynamically pass values to the gauge, you use the JavaScript API.

A cylinder gauge configured to receive real-time updates using the JavaScript API looks like this:

FusionCharts will load here..
{ "chart": { "theme": "fint", "caption": "Diesel Level in Generator", "subcaption": "Bakersfield Central", "lowerLimit": "0", "upperLimit": "120", "lowerLimitDisplay": "Empty", "upperLimitDisplay": "Full", "numberSuffix": " ltrs", "showValue": "1", "chartBottomMargin": "25" }, "value": "110" }
{
    "chart": {
        "theme": "fint",
        "caption": "Diesel Level in Generator",
        "subcaption": "Bakersfield Central",
        "lowerLimit": "0",
        "upperLimit": "120",
        "lowerLimitDisplay": "Empty",
        "upperLimitDisplay": "Full",
        "numberSuffix": " ltrs",
        "showValue": "1",
        "chartBottomMargin": "25"
    },
    "value": "110"
}
<html>
<head>
<title>My first chart using FusionCharts Suite XT</title>
<script type="text/javascript" src="http://static.fusioncharts.com/code/latest/fusioncharts.js"></script>
<script type="text/javascript" src="http://static.fusioncharts.com/code/latest/themes/fusioncharts.theme.fint.js?cacheBust=56"></script>
<script type="text/javascript">
  FusionCharts.ready(function(){
    var fusioncharts = new FusionCharts({
    type: 'cylinder',
    dataFormat: 'json',
    id: 'fuelMeter-1',
    renderAt: 'chart-container',
    width: '250',
    height: '350',
    dataSource: {
        "chart": {
            "theme": "fint",
            "caption": "Diesel Level in Generator",
            "subcaption": "Bakersfield Central",
            "lowerLimit": "0",
            "upperLimit": "120",
            "lowerLimitDisplay": "Empty",
            "upperLimitDisplay": "Full",
            "numberSuffix": " ltrs",
            "showValue": "1",
            "chartBottomMargin": "25"
        },
        "value": "110"
    },
    "events": {
        "rendered": function(evtObj, argObj) {
            var fuelVolume = 110,
                gaugeRef = evtObj.sender;
            gaugeRef.chartInterval = setInterval(function() {

                (fuelVolume < 10) ? (fuelVolume = 110) : "";
                var consVolume = fuelVolume - (Math.floor(Math.random() * 3));
                gaugeRef.feedData("&value=" + consVolume);
                fuelVolume = consVolume;
            }, 3000);
        },
        "disposed": function(evt, arg) {
            clearInterval(evt.sender.chartInterval);
        }
    }
}
);
    fusioncharts.render();
});
</script>
</head>
<body>
  <div id="chart-container">FusionCharts XT will load here!</div>
</body>
</html>

The cylinder gauge exposes the following JavaScript APIs:

Function Name Parameter Description

feedData(strData)

strData

This method feeds real-time data to the chart using the JavaScript API. The data has to be in the same format as provided by real-time data provider page.

getData()

None

This method returns the data currently being shown by the gauge.

setData(value)

value

This method sets the data for the chart. The value should be within the limits of the gauge.

Configuring Real-time Updates using Server-side Script

Another way to update a chart in real-time is by using server-side script.

A cylinder gauge configured to receive real-time updates using the server-side script looks like this:

FusionCharts will load here..
{ "chart": { "theme": "fint", "caption": "Diesel Level in Generator", "subcaption": "Bakersfield Central", "lowerLimit": "0", "upperLimit": "120", "lowerLimitDisplay": "Empty", "upperLimitDisplay": "Full", "numberSuffix": " ltrs", "showValue": "1", "chartBottomMargin": "45", "dataStreamUrl": "../../../resources/php/gauge-and-widgets-guide-cylinder-gauge-real-time-gauges-php-1.php", "refreshInterval": "2", "refreshInstantly": "1" }, "value": "110" }
{
    "chart": {
        "theme": "fint",
        "caption": "Diesel Level in Generator",
        "subcaption": "Bakersfield Central",
        "lowerLimit": "0",
        "upperLimit": "120",
        "lowerLimitDisplay": "Empty",
        "upperLimitDisplay": "Full",
        "numberSuffix": " ltrs",
        "showValue": "1",
        "chartBottomMargin": "45",
        "dataStreamUrl": "../../../resources/php/gauge-and-widgets-guide-cylinder-gauge-real-time-gauges-php-1.php",
        "refreshInterval": "2",
        "refreshInstantly": "1"
    },
    "value": "110"
}
<html>
<head>
<title>My first chart using FusionCharts Suite XT</title>
<script type="text/javascript" src="http://static.fusioncharts.com/code/latest/fusioncharts.js"></script>
<script type="text/javascript" src="http://static.fusioncharts.com/code/latest/themes/fusioncharts.theme.fint.js?cacheBust=56"></script>
<script type="text/javascript">
  FusionCharts.ready(function(){
    var fusioncharts = new FusionCharts({
    type: 'cylinder',
    dataFormat: 'json',
    id: 'fuelMeter-2',
    renderAt: 'chart-container',
    width: '250',
    height: '350',
    dataSource: {
        "chart": {
            "theme": "fint",
            "caption": "Diesel Level in Generator",
            "subcaption": "Bakersfield Central",
            "lowerLimit": "0",
            "upperLimit": "120",
            "lowerLimitDisplay": "Empty",
            "upperLimitDisplay": "Full",
            "numberSuffix": " ltrs",
            "showValue": "1",
            "chartBottomMargin": "45",
            "dataStreamUrl": "../../../resources/php/gauge-and-widgets-guide-cylinder-gauge-real-time-gauges-php-1.php",
            "refreshInterval": "2",
            "refreshInstantly": "1"
        },
        "value": "110"
    }
}
);
    fusioncharts.render();
});
</script>
</head>
<body>
  <div id="chart-container">FusionCharts XT will load here!</div>
</body>
</html>

The new attributes that need to be added for receiving real-time updates from the server are:

Attribute Name Description

dataStreamURL

This attribute is used to set 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 dataStreamURL.

This page needs to be on the same sub-domain on which the chart is hosted and invoked from. Otherwise, security measures will restrict it from accessing the data and hence the real-time feature won’t work.

Example: dataStreamURL=’liveQuote.aspx?name=xyz’

refreshInterval

This attribute is used to specify the number of seconds after which the chart will look for new data. This process will happen continuously - i.e., if you specify 5 seconds here, the chart will look for new data every 5 seconds.

dataStamp

This attribute is used to set a 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 Adding Data Stamp | FusionCharts article.

Stopping and Restarting Real-time Updates

You can stop the chart from polling the server for any more real-time updates. To do this, you use the stopUpdate command as shown below:

"stopUpdate": 1;

To restart updates from the server, use the startUpdate command from the server as shown below:

"startUpdate": 1;

A cylinder gauge configured to allow stopping and restarting real-time updates from the server, looks like this:

FusionCharts will load here..
{ "chart": { "theme": "fint", "caption": "Diesel Level in Generator", "subcaption": "Bakersfield Central", "lowerLimit": "0", "upperLimit": "120", "dataStreamUrl": "../../../resources/php/gauge-and-widgets-guide-cylinder-gauge-real-time-gauges-php-2.php", "lowerLimitDisplay": "Empty", "upperLimitDisplay": "Full", "numberSuffix": " ltrs", "showValue": "1", "chartBottomMargin": "45", "refreshInterval": "2" }, "value": "110" }
{
    "chart": {
        "theme": "fint",
        "caption": "Diesel Level in Generator",
        "subcaption": "Bakersfield Central",
        "lowerLimit": "0",
        "upperLimit": "120",
        "dataStreamUrl": "../../../resources/php/gauge-and-widgets-guide-cylinder-gauge-real-time-gauges-php-2.php",
        "lowerLimitDisplay": "Empty",
        "upperLimitDisplay": "Full",
        "numberSuffix": " ltrs",
        "showValue": "1",
        "chartBottomMargin": "45",
        "refreshInterval": "2"
    },
    "value": "110"
}
<html>
<head>
<title>My first chart using FusionCharts Suite XT</title>
<script type="text/javascript" src="http://static.fusioncharts.com/code/latest/fusioncharts.js"></script>
<script type="text/javascript" src="http://static.fusioncharts.com/code/latest/themes/fusioncharts.theme.fint.js?cacheBust=56"></script>
<script type="text/javascript">
  FusionCharts.ready(function(){
    var fusioncharts = new FusionCharts({
    type: 'cylinder',
    renderAt: 'chart-container',
    id: 'cs-cylinder-gauge-3',
    width: '250',
    height: '350',
    dataFormat: 'json',
    dataSource: {
        "chart": {
            "theme": "fint",
            "caption": "Diesel Level in Generator",
            "subcaption": "Bakersfield Central",
            "lowerLimit": "0",
            "upperLimit": "120",
            "dataStreamUrl": "../../../resources/php/gauge-and-widgets-guide-cylinder-gauge-real-time-gauges-php-2.php",
            "lowerLimitDisplay": "Empty",
            "upperLimitDisplay": "Full",
            "numberSuffix": " ltrs",
            "showValue": "1",
            "chartBottomMargin": "45",
            "refreshInterval": "2",
        },
        "value": "110"

    },
    events: {
        "beforeRender": function(evt, args) {
            // creating div for controllers
            var controllers = document.createElement('div'),
                isStopped = false,
                gaugeRef = evt.sender;
            controllers.setAttribute('id', 'controllers');

            // Create checkbox inside div
            controllers.innerHTML = '<input type="button" value="Stop Update" id="toggleBtn" style="margin-left:5px;margin-top:5px;font-size:13px;padding:2px;" />';
            args.container.parentNode.insertBefore(controllers, args.container.nextSibling);

            // setting css styles for controllers div
            controllers.style.cssText = "text-align: center;";
            var btn = document.getElementById('toggleBtn'),
                startStopUpdate = function() {
                    if (!isStopped) {
                        isStopped = true
                        btn.value = "Restart Update";
                        gaugeRef.stopUpdate();
                    } else {
                        isStopped = false;
                        btn.value = "Stop Update";
                        gaugeRef.restartUpdate();
                    }
                }

            btn.addEventListener && btn.addEventListener("click", startStopUpdate);

        }
    }
}
);
    fusioncharts.render();
});
</script>
</head>
<body>
  <div id="chart-container">FusionCharts XT will load here!</div>
</body>
</html>

The cylinder gauge exposes the following JavaScript APIs for stop update and restart update:

Function Name Parameter Description

stopUpdate()

None

This method stops the chart from self-updating.

restartUpdate()

None

If you’ve stopped the update of the chart, you can resume the update using this method.

Configuring Real-time Events

You can use the realTimeUpdateCompete and the realTimeUpdateError events to track real-time updates on charts and gauges.

The realTimeUpdateComplete Event

This event is raised when a real-time gauge or chart completes updating data.

A cylinder gauge configured to listen to the realTimeUpdateComplete event looks like this:

FusionCharts will load here..
{ "chart": { "theme": "fint", "caption": "Diesel Level in Generator", "subcaption": "Bakersfield Central", "lowerLimit": "0", "upperLimit": "120", "lowerLimitDisplay": "Empty", "upperLimitDisplay": "Full", "numberSuffix": " ltrs", "showValue": "0", "chartBottomMargin": "60" }, "value": "110", "annotations": { "origw": "400", "origh": "190", "autoscale": "1", "groups": [ { "id": "range", "items": [ { "id": "rangeBg", "type": "rectangle", "x": "$canvasCenterX-125", "y": "$chartEndY-50", "tox": "$canvasCenterX +145", "toy": "$chartEndY-95", "fillcolor": "#6caa03" }, { "id": "rangeText", "type": "Text", "fontSize": "11", "fillcolor": "#333333", "text": "Available Volume : 110 ltrs", "x": "$chartCenterX-35", "y": "$chartEndY-70" } ] } ] } }
{
    "chart": {
        "theme": "fint",
        "caption": "Diesel Level in Generator",
        "subcaption": "Bakersfield Central",
        "lowerLimit": "0",
        "upperLimit": "120",
        "lowerLimitDisplay": "Empty",
        "upperLimitDisplay": "Full",
        "numberSuffix": " ltrs",
        "showValue": "0",
        "chartBottomMargin": "60"
    },
    "value": "110",
    "annotations": {
        "origw": "400",
        "origh": "190",
        "autoscale": "1",
        "groups": [
            {
                "id": "range",
                "items": [
                    {
                        "id": "rangeBg",
                        "type": "rectangle",
                        "x": "$canvasCenterX-125",
                        "y": "$chartEndY-50",
                        "tox": "$canvasCenterX +145",
                        "toy": "$chartEndY-95",
                        "fillcolor": "#6caa03"
                    },
                    {
                        "id": "rangeText",
                        "type": "Text",
                        "fontSize": "11",
                        "fillcolor": "#333333",
                        "text": "Available Volume : 110 ltrs",
                        "x": "$chartCenterX-35",
                        "y": "$chartEndY-70"
                    }
                ]
            }
        ]
    }
}
<html>
<head>
<title>My first chart using FusionCharts Suite XT</title>
<script type="text/javascript" src="http://static.fusioncharts.com/code/latest/fusioncharts.js"></script>
<script type="text/javascript" src="http://static.fusioncharts.com/code/latest/themes/fusioncharts.theme.fint.js?cacheBust=56"></script>
<script type="text/javascript">
  FusionCharts.ready(function(){
    var fusioncharts = new FusionCharts({
    type: 'cylinder',
    dataFormat: 'json',
    id: 'fuelMeter-4',
    renderAt: 'chart-container',
    width: '250',
    height: '350',
    dataSource: {
        "chart": {
            "theme": "fint",
            "caption": "Diesel Level in Generator",
            "subcaption": "Bakersfield Central",
            "lowerLimit": "0",
            "upperLimit": "120",
            "lowerLimitDisplay": "Empty",
            "upperLimitDisplay": "Full",
            "numberSuffix": " ltrs",
            "showValue": "0",
            "chartBottomMargin": "60"
        },
        "value": "110",

        "annotations": {
            "origw": "400",
            "origh": "190",
            "autoscale": "1",
            "groups": [{
                "id": "range",
                "items": [{
                    "id": "rangeBg",
                    "type": "rectangle",
                    "x": "$canvasCenterX-125",
                    "y": "$chartEndY-50",
                    "tox": "$canvasCenterX +145",
                    "toy": "$chartEndY-95",
                    "fillcolor": "#6caa03"
                }, {
                    "id": "rangeText",
                    "type": "Text",
                    "fontSize": "11",
                    "fillcolor": "#333333",
                    "text": "Available Volume : 110 ltrs",
                    "x": "$chartCenterX-35",
                    "y": "$chartEndY-70"
                }]
            }]
        }
    },
    "events": {
        "rendered": function(evtObj, argObj) {
            var gaugeRef = evtObj.sender,
                fuelVolume = 110;
            gaugeRef.chartInterval = setInterval(function() {
                (fuelVolume < 10) ? (fuelVolume = 110) : "";
                var consVolume = fuelVolume - (Math.floor(Math.random() * 3));
                gaugeRef.feedData("&value=" + consVolume);
                fuelVolume = consVolume;
            }, 1000);
        },
        //Using real time update event to update the annotation
        //showing available volume of Diesel
        "realTimeUpdateComplete": function(evt, arg) {
            var annotations = evt.sender.annotations,
                dataVal = evt.sender.getData(),
                colorVal = (dataVal >= 70) ? "#6caa03" : ((dataVal <= 25) ? "#e44b02" : "#f8bd1b");
            //Updating value
            annotations && annotations.update('rangeText', {
                "text": "Available Volume: " + dataVal + " ltrs"
            });
            //Changing background color as per value
            annotations && annotations.update('rangeBg', {
                "fillcolor": colorVal
            });
        },
        "disposed": function(evt, arg) {
            clearInterval(evt.sender.chartInterval);
        }
    }
}
);
    fusioncharts.render();
});
</script>
</head>
<body>
  <div id="chart-container">FusionCharts XT will load here!</div>
</body>
</html>

Given below is a brief description of the realTimeUpdateComplete event:

Event Name Description

realTimeUpdateComplete

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:

Real-time update using datastreamURL

Real-time update using JavaScript API (using setData, feedData, setDataForId functions)

Real-time update of the gauge through user interaction (through edit mode)


The event arguments provided in the advanced model are:

eventObject: This object contains the eventId, eventType, and sender properties.

argumentsObject: This object contains the values of the updated data and the previous data.

The realTimeUpdateError Event

This event is raised when an error occurs while updating data in a real-time gauge or chart. This event passes the HTTP Status (as number) of the error occurred as shown below:

A cylinder gauge configured to listen to the realTimeUpdateError event looks like this:

FusionCharts will load here..
{ "chart": { "theme": "fint", "caption": "Diesel Level in Generator", "subcaption": "Bakersfield Central", "lowerLimit": "0", "upperLimit": "120", "lowerLimitDisplay": "Empty", "upperLimitDisplay": "Full", "numberSuffix": " ltrs", "showValue": "0", "chartBottomMargin": "60", "dataStreamURL": "dummyErrorURL/cylinderData.php" }, "value": "110" }
{
    "chart": {
        "theme": "fint",
        "caption": "Diesel Level in Generator",
        "subcaption": "Bakersfield Central",
        "lowerLimit": "0",
        "upperLimit": "120",
        "lowerLimitDisplay": "Empty",
        "upperLimitDisplay": "Full",
        "numberSuffix": " ltrs",
        "showValue": "0",
        "chartBottomMargin": "60",
        "dataStreamURL": "dummyErrorURL/cylinderData.php"
    },
    "value": "110"
}
<html>
<head>
<title>My first chart using FusionCharts Suite XT</title>
<script type="text/javascript" src="http://static.fusioncharts.com/code/latest/fusioncharts.js"></script>
<script type="text/javascript" src="http://static.fusioncharts.com/code/latest/themes/fusioncharts.theme.fint.js?cacheBust=56"></script>
<script type="text/javascript">
  FusionCharts.ready(function(){
    var fusioncharts = new FusionCharts({
    type: 'cylinder',
    dataFormat: 'json',
    id: 'fuelMeter-5',
    renderAt: 'chart-container',
    width: '250',
    height: '350',
    dataSource: {
        "chart": {
            "theme": "fint",
            "caption": "Diesel Level in Generator",
            "subcaption": "Bakersfield Central",
            "lowerLimit": "0",
            "upperLimit": "120",
            "lowerLimitDisplay": "Empty",
            "upperLimitDisplay": "Full",
            "numberSuffix": " ltrs",
            "showValue": "0",
            "chartBottomMargin": "60",
            "dataStreamURL": "dummyErrorURL/cylinderData.php"
        },
        "value": "110"
    },
    "events": {
        'beforeRender': function(evt, args) {

            // creating div for controllers
            var controllers = document.createElement('div'),
                container = document.getElementById('chart-container');
            // Create checkbox inside div

            controllers.innerHTML = '<div id="chart-message"></div>';

            controllers.setAttribute('id', 'controllers');
            // setting css styles for controllers div
            controllers.style.cssText = "text-align: center;min-height: 50px;color : #cc0000;font-family : Arial, Helvetica, sans-serif;font-size : 14px;margin-top : 10px;";
            args.container.parentNode.insertBefore(controllers, args.container.nextSibling);
        },

        //Using real time update error event
        "realtimeUpdateError": function(evtObj, argObj) {
            var msgDiv = document.getElementById('chart-message');
            msgDiv.innerHTML = "<b>Error Occured !</b><br> Status Code : " + argObj.httpStatus;
        }
    }
}
);
    fusioncharts.render();
});
</script>
</head>
<body>
  <div id="chart-container">FusionCharts XT will load here!</div>
</body>
</html>

Given below is a brief description of the realtimeUpdateError event:

Event Name Description

realtimeUpdateError

This event is raised when an error occurs while performing real-time update using datastreamURL.
The event arguments provided in the advanced model are:

1. eventObject : This object contains eventId, eventType and sender properties.

2. argumentsObject : This object contains the property listed below:

    a. httpStatus : It contains the HTTP Error status value as number (e.g., 404)

Troubleshooting Real-time Gauges

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 running the chart from local file system (C:\ , D:\). Instead, run the chart from behind a server (localhost - IIS, Apache etc.). This is because, by default, security settings do not allow the chart to perform JavaScript interactions on the local file system.

Top