Listening to Events

The FusionCharts JavaScript Class API provides a number of events for real-time charts. These events are categorized into two broad groups - simple events and advanced events. Each event provides arguments to the event-listeners.

In the advanced model, two event parameters are passed to the event listener function. The first parameter, eventObject is is structurally common for all events. The second parameter, argumentsObject contains event specific properties.

In this section, you will be introduced to the:

• Event parameters in the simple model

• Event parameters in the advanced model

• Real-time events

Event Parameters in the Simple Model

In the simple events model, most events (except the FC_Exported and the FC_Resized events) provide the DOM Id of the source chart - the chart that raised the event.

Event Parameters in the Advanced Model

In the advanced model, two event parameters are passed to the event listener function. The first parameter, eventObject is is structurally common for all events. The second parameter, argumentsObject contains event specific properties.

The details of these objects are explained below:

• eventObject, the first argument, provides details of the event. This object has the following three properties:

• eventId : An unique id given to the event.

• eventType : A string containing the name or the event type e.g. “rendered” etc.

• sender : A FusionCharts JavaScript Object reference to the chart that has raised the event.

• argumentsObject, the second argument, contains details of the event fired. Depending on the type of event raised, the properties of the object vary.

For more information on simple and advanced events and the argumentsObject for each event, refer to the FusionCharts Events API page.

Real-time Events

The realtimeUpdateComplete Event

The FusionCharts JavaScript Class API realTimeUpdateComplete event is raised every time a real-time chart or gauge updates itself with new data.

A real-time column chart configured to listen to the realTimeUpdateComplete event is shown below:

The above chart shows the real-time statistics of footfalls at the Bakersfield Central outlet. The chart is updated with new data every five seconds. Whenever there is a data update, the realTimeUpdateComplete event is fired. The event is configured to then retrieve the last data updated and display it in an HTML table rendered below the chart.

The data structure needed to render the above chart is given below:

• JSON
• XML

{
    "chart": {
        "caption": "Harry's Supermart - Bakersfield Central",
        "subCaption": "Footfalls",
        "showrealtimevalue": "1",
        "paletteColors": "#008ee4,#9b59b6",
        "borderAlpha": "0",
        "yaxismaxvalue": "20",
        "numdisplaysets": "10",
        "usePlotGradientColor": "0",
        "plotBorderAlpha": "0",
        "canvasBorderAlpha": "20",
        "labeldisplay": "rotate",
        "slantLabels": "1",
        "showLegend": "0",
        "bgAlpha": "0",
        "showValues": "0",
        "numbersuffix": " Customers",
        "showlabels": "1",
        "animation": "0",
        "showRealTimeValue": "0"
    },
    "categories": [
        {
            "category": [
                {
                    "label": "Start"
                }
            ]
        }
    ],
    "dataset": [
        {
            "seriesname": "Footfall",
            "alpha": "100",
            "data": [
                {
                    "value": "5"
                }
            ]
        }
    ]
}

More details pertaining to this event are given in the table below:

The realtimeUpdateError Event

The realTimeUpdateError event is raised when an error occurs while performing a real-time update from the data provider page specified using the dataStreamURL attribute.

A real-time column chart configured to listen to the realTimeUpdateError event is shown below:

The data structure needed to render the above chart is given below:

• JSON
• XML

{
    "chart": {
        "caption": "Harry's Supermart - Bakersfield Central",
        "subCaption": "Footfalls",
        "showrealtimevalue": "1",
        "dataStreamURL": "explore/data.php",
        "paletteColors": "#008ee4,#9b59b6",
        "borderAlpha": "0",
        "yaxismaxvalue": "20",
        "numdisplaysets": "10",
        "usePlotGradientColor": "0",
        "plotBorderAlpha": "0",
        "canvasBorderAlpha": "20",
        "labeldisplay": "rotate",
        "slantLabels": "1",
        "showLegend": "0",
        "bgAlpha": "0",
        "showValues": "0",
        "numbersuffix": " Customers",
        "showlabels": "1",
        "animation": "0",
        "showRealTimeValue": "0"
    },
    "categories": [
        {
            "category": [
                {}
            ]
        }
    ],
    "dataset": [
        {
            "seriesname": "Footfall",
            "alpha": "100"
        }
    ]
}

In the above data, the URL to a fake data provider page has passed as value to the dataStreamURL attribute. We have done this to trigger the realTimeUpdateError event. When this event is raised, a custom error message and the error status code are displayed.

More details pertaining to this event are given in the table below:

There! You have now seen how you can configure events for real-time charts.