You are viewing documentation for an older version. For current documentation - click here.
Real-time support

The gauges in FusionWidgets XT pack are real time gauges that can continuously request new data from the server and display the same, without involving any page refreshes. You can specify the URL of the data provider and the time interval (in seconds), after which the gauge will look for new data.

The data provider page needs to be a page at your server-side, which when invoked by linear gauge, will output the new data in the format explained below.

Real-time data format

The real-time data format for gauges depends on:

  • Value to be passed
  • Whether you're using Message Logger for the chart?
  • Commands for the chart - like stop update etc.

Let's quickly see examples of each one of them.
Data value update

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=34

Here, the output is a single value, 34. So, when FusionWidgets XT will read this value, it will update the chart by setting its value to 34 (if the data is within range).

Stopping real-time updates from server

If you wish to stop the chart from polling the server for any more real-time updates, you can send the following command from server to do so:

&stopUpdate=1

After stopping the update, it can be restarted either using user interaction (right click context menu) or using client-side JavaScript.

Sending messages pertinent to Message logger
 
The gauge can show message logger like data streaming charts. There are various parameters which you can specify for message logger. All of them have been explained in the Message Logger section.
 
Creating the real-time gauge

To create any real-time gauge, you'll need to assimilate the following things:

  1. Chart SWF file and FusionCharts JavaScript Class
  2. XML file that initializes the chart and tells it where to pull the real time data from
  3. Real time data provider page that provides updated data to chart in real-time data format.

We're already familiar with XML for the chart. The new attributes that need to be added for real-time update are:

Attribute Name Type / Range Description
dataStreamURL URL This parameter sets the path of the page which is supposed to relay real-time data to the chart. If you've special characters as a part of your data stream URL, like ? or &, you'll need 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, the Flash sandbox security will restrict it from accessing the data and hence the real-time feature won't work.
Example: dataStreamURL='liveQuote.aspx?name=xyz'
refreshInterval Number For this parameter, you can 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 String 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

Shown below is an example chart XML:

 
<chart lowerLimit="0" upperLimit="100" lowerLimitDisplay="Bad" upperLimitDisplay="Good" palette="1" numberSuffix="%" chartRightMargin="20" decimals="0" dataStreamURL="RealTimeData.asp" refreshInterval="3">
  <colorRange>
    <color minValue="0" maxValue="75" code="FF654F" label="Bad"/>
    <color minValue="75" maxValue="90" code="F6BD0F" label="Moderate"/>
    <color minValue="90" maxValue="100" code="8BBA00" label="Good"/>
  </colorRange>
  <value>43</value>
  <styles>
    <definition>
      <style type="font" name="myValueFont" bgColor="F1f1f1" borderColor="999999"/>
    </definition>
    <application>
      <apply toObject="Value" styles="myValueFont"/>
    </application>
  </styles>
</chart>
{
  "chart": {
    "lowerlimit": "0",
    "upperlimit": "100",
    "lowerlimitdisplay": "Bad",
    "upperlimitdisplay": "Good",
    "palette": "1",
    "numbersuffix": "%",
    "chartrightmargin": "20",
    "decimals": "0",
    "datastreamurl": "RealTimeData.asp",
    "refreshinterval": "3"
  },
  "colorrange": {
    "color": [
      {
        "minvalue": "0",
        "maxvalue": "75",
        "code": "FF654F",
        "label": "Bad"
      },
      {
        "minvalue": "75",
        "maxvalue": "90",
        "code": "F6BD0F",
        "label": "Moderate"
      },
      {
        "minvalue": "90",
        "maxvalue": "100",
        "code": "8BBA00",
        "label": "Good"
      }
    ]
  },
  "value": "43",
  "styles": {
    "definition": [
      {
        "type": "font",
        "name": "myValueFont",
        "bgcolor": "F1f1f1",
        "bordercolor": "999999"
      }
    ],
    "application": [
      {
        "toobject": "Value",
        "styles": "myValueFont"
      }
    ]
  }
}

Here, we've set dataStreamURL='RealTimeData.asp' refreshInterval='3', which tells the chart to poll new data from RealTimeData.asp every 3 seconds.

For the sake of demo, RealTimeData.asp returns random value within 100% in the format:

&value=84

When this value is read by the gauge, it will update its display to reflect the updated value.

Troubleshooting
 
If the chart renders initially, but doesn't update in real time, do the following:
 
  • Check if you've specified a correct and valid path for dataStreamURL in XML/JSON data
  • Check if you've specified a valid value for refreshInterval in your XML/JSON data
  • Check if dataStreamURL is returning proper data. To test this, just open your browser and run this page. It should return the data in text format.
  • Make sure the output data doesn't contain any carriage returns (new-line characters) or HTML elements. In many scripting languages, these are automatically added. You'll need to remove them.
  • You also need to make sure that the page which provides the incremental update data to the charts must be hosted on the same sub-domain in which the charts are hosted - otherwise, owing to security restrictions, the charts won't be able to receive updated data. Due to security restrictions, charts are allowed to retrieve data only from the same sub-domain in which the charts are residing. Data can only be loaded from a domain that is an exact match to the location of the charts, including sub-domains. For this reason, a chart residing at server1.mydomain.com will not be able to access data from mydomain.com.

    If you wish to load data from a different domain, you can set up a proxy page at the same sub-domain that will actually request data from the distant domain and then relay it to the charts. You must be able to upload and run a server-side script on a server in the same domain as the charts. In this method, a chart accesses the script, which loads the information, retrieves it and returns the information back to the chart. This method is best if the server hosting the data is not under your control (for example, a public source or a web service).

  • If you are using Flash charts, switch on the debug mode of chart. It will provide you with a lot of valuable information when debugging.