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:

&value=75

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:

FusionCharts should load here..

Given below is a brief description of the JavaScript API methods used to configure real-time updates:

Function Name Parameter Description
feedData(strData) 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:

...

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:

&value=34|25

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:

FusionCharts should load here..

The data structure needed to update multiple pointers is given below:

...

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:

&gGrovePointer=65&bFieldPointer=80

This will change the value of pointer 1 (with id as gGrovePointer) to 65 and pointer 2 to 80.

A linear gauge configured to update the values of multiple pointers using named IDs looks like this:

FusionCharts should load here..

Given below is a brief description of the JavaScript API methods used to update pointers using their IDs:

Function Name Parameter Description
feedData(strData) 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.
getData(pointerIndex) 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.
getDataForId(pointerId) pointerId This method returns the data for the given pointer using its defined ID.
setData(pointerIndex, value) 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.
setDataForId(pointerId, value) pointerId, value This method returns the data for the given pointer using its defined ID. The ID of the pointer is defined in XML using:
"pointer": [{ ... "id": "XYZ", ... }]

The data structure needed to update pointers using IDs is given below:

...

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.

Additionally, we can control the annotations using JavaScript API, which has been discussed in the annotations sections.

Retrieving data from Chart

We can retrieve data from gauge once the data has been updated.

A linear gauge configured to retrieve data from the chart looks like this:

FusionCharts should load here..

The data structure of the above sample is as follows:

...

Real-time Updates using Server-side Script

An LED gauge updated in real-time using a server-side script looks like this:

FusionCharts should load here..

Given below is a brief description of the attributes used to configure real-time updates using server-side scripts:

Attribute Name Description
dataStreamURL This parameter sets the path of the page which is supposed to relay real-time data to the chart. If we have special characters as a part of your data stream URL, like ? or &, we need to URL Encode the entire dataStreamURL attribute. This page needs to be on the same sub-domain on which the chart is hosted and invoked from. Otherwise, security will restrict it from accessing the data and hence the real-time feature won't work.
Example: dataStreamURL='liveQuote.aspx?name=xyz'
refreshInterval 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.
dataStamp Constantly changing data stamp that can be added to real time Data URL, so as to maintain a state. Please see the section Real time capabilities > Adding Data Stamp

The data structure needed to to configure real-time updates using server-side script is given below:

...

Stopping/Restarting Updates

An LED gauge configured to stop receiving real-time updates looks like this:

FusionCharts should load here..

stopUpdate and startUpdate that involves server side interactivity. (Validation Pending)

Given below is a brief description of the JavaScript API used tos stop receiving real-time updates:

Function Name Parameter Description
stopUpdate() None This method stops the chart from self-updating.

The data structure needed to stop receiving real-time updates is given below:

...

Given below is a brief description of the JavaScript API used to restart real-time updates:

Function Name Parameter Description
restartUpdate() None If you've stopped the real-time update of the chart, you can resume the update using this method.

The data structure needed to restart real-time updates for the chart is given below:

...

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:

FusionCharts should load here..

Given below is a brief description of the realTimeUpdateComplete event:

Attribute Name Description
realtimeUpdateComplete This event is raised every 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.
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:
eventObject : This object contains eventId, eventType and sender properties.
argumentsObject : This object contains the property listed below:
    httpStatus : It contains the HTTP Error status value as number (e.g., 404)

The data structure needed to configure the realTimeUpdateComplete event for real-time angular gauge is given below:

...

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_Rendered function or define the event listener for Rendered event 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.