Handling Events

FusionCharts Suite XT includes an exhaustive set of events that let you interact with the product’s various charts, gauges, and maps at different stages of their lifecycle—for example, when a chart completes rendering, when chart data is updated, when a data plot is clicked, and so on.

To configure events for charts, you need to:

• Decide the event you want to configure and the response you want when it is triggered
• Create an event listener that ‘listens’ for the event being triggered and executes the required response

This article describes how events in FusionCharts Suite XT are handled.

A simple example to understand this would be to use the renderComplete event to render a message every time, like the event name says, the chart completes rendering.

Start with a simple column 2D chart, as shown below:

The data structure for this column 2D chart is given below:

• JSON
• XML

{
    "chart": {
        "caption": "Quarterly Revenue for FY2013-2014",
        "subCaption": "Harry's SuperMart",
        "xAxisName": "Quarter",
        "yAxisName": "Revenue",
        "numberPrefix": "$",
        "theme": "fint"
    },
    "data": [
        {
            "label": "Q1",
            "value": "420000"
        },
        {
            "label": "Q2",
            "value": "810000"
        },
        {
            "label": "Q3",
            "value": "720000"
        },
        {
            "label": "Q4",
            "value": "550000"
        }
    ]
}

Now, read on to understand how the renderComplete event will be handled for the above column 2D chart.

Defining the Listener Function

To configure the renderComplete event for the column 2D chart, first define the listener function for the event in the JSON/XML code for the chart.

A listener function is a JavaScript function that accepts two optional arguments: eventObj and eventArgs. These arguments receive information specific to the event to which the listener is attached.

For more details on the arguments passed to the event listeners, read the FusionCharts API reference for event listeners.

The code snippet to define an event listener is shown below:

...
var myEventListener = function (eventObj, eventArgs) {
   console.log(eventObj.eventType + " was raised by the chart whose ID is " + eventObj.sender.id);
};
...

The listener definition here uses the eventObj object to extract the type of event triggered and the ID of the chart on which the event is triggered.

Now for the listener function to perform its intended task, it has to be attached to an event. In context to the example above, this listener function will have to be attached to the renderComplete event.
This is done using the addEventListener() function, available on every instance of the chart.

For the renderComplete event in the above example, the listener is added right before the chart is rendered.

It is not mandatory for all events to be registered before the renderComplete event is called. They can be registered just before you need to call them.

The addEventListener() function takes the following two parameters:

Once the listener function is defined, the line of code shown below is used to attach the listener function to the event:

...
revenueChart.addEventListener(“renderComplete”, myEventListener);
...

Your column 2D chart is now configured to listen to the renderComplete event.

Open the JavaScript console (the listener function is configured to log a message in the console) to see the following message:

renderComplete event was raised by the chart whose ID is chartobject-2.

The complete data structure of the chart, with the listener definition, is given below:

FusionCharts.ready(function () {
  var revenueChart = new FusionCharts({
        type: 'column2d',
        renderAt: 'chart-container',
        width: '400',
        height: '300',
        dataFormat: 'json',
        dataSource: {
            "chart": {
                "caption": "Quarterly Revenue for FY2013-2014",
                "subCaption": "Harry's SuperMart",
                "xAxisName": "Quarter",
                "yAxisName": "Revenue",
                "numberPrefix": "$",
                "theme": "fint"
            },
            "data": [
                {
                    "label": "Q1",
                    "value": "420000"
                },
                {
                    "label": "Q2",
                    "value": "810000"
                },
                {
                    "label": "Q3",
                    "value": "720000"
                },
                {
                    "label": "Q4",
                    "value": "550000"
                }
            ]

            }
    });

    var myEventListener = function (eventObj, eventArgs) {console.log(eventObj.eventType + " was raised by the chart whose ID is " + eventObj.sender.id);
      };

    revenueChart.addEventListener("renderComplete", myEventListener);
    revenueChart.render();
  });

Embedding the Listener Function Inside the Event Listener

In the example above, the listener function is defined separately using the myEventListener variable. An alternative way to do this is to embed the anonymous function inside the event listener.

This is how the code will then be re-written:

...
revenueChart.addEventListener("renderComplete", function(eventObj, eventArgs) {
   console.log(eventObj.eventType + " was raised by the chart whose ID is " + eventObj.sender.id);
});
...

Passing Event Listeners During Chart Creation

Another more unified way to pass all event listeners for a chart is to do so while creating the chart. This is done by passing all events using the events property within the object passed as the constructor parameter.

The renderComplete event for the above column 2D chart can thus be configured as:

...
 events:{
            'renderComplete': function(eventObj, args) {
               console.log(eventObj.eventType + " was raised by the chart whose ID is " + eventObj.sender.id);
            }
        }

...

Listening to Events Triggered for All Charts on a Page

Events can be attached to the windows.FusionCharts object. Attaching events to the FusionCharts constructor causes the event listener to be attached to all the charts on a page-the ones that are already created as well as the ones that will be created later.

Add the following code lines to the JS code for the above column 2D chart configured for the renderComplete event:

...
FusionCharts.addEventListener("renderComplete", function(eventObj, eventArgs) {
   console.log(eventObj.eventType + " was raised by the chart whose ID is " + eventObj.sender.id);
});
...

When the JavaScript console is opened on a page with multiple charts, a list of messages in the console show that therenderComplete event has been triggered for all charts on the page.

Listening to Multiple Events Triggered for One Chart

To listen to multiple events for one chart using just one event listener, use the code snippet shown below:

...
var myEventListener = function (eventObj, eventArgs) {
   console.log(eventObj.eventType + " was raised by the chart whose ID is " + eventObj.sender.id);
};

myChart.addEventListener("initialized", myEventListener);
myChart.addEventListener("dataUpdated", myEventListener);
myChart.addEventListener("renderComplete", myEventListener);
myChart.addEventListener("disposed", myEventListener);

});
...

The above code configures four events, to be triggered during different stages of the chart’s lifecycle.

To optimize the above code, the last four lines of event attachment can be reduced to a single code line, where event names are passed as an array to the addEventListener() function. Use of the myEventListener variable can also be eliminated by passing the listener directly as an anonymous function.

This is how the revised code then looks:

...
revenueChart.addEventListener(["initialized",
   "dataUpdated",
   "renderComplete",
   "disposed"], function (eventObj, eventArgs) {
   console.log(eventObj.eventType + " was raised by the chart whose ID is " + eventObj.sender.id);
});
...

Cancelling Event Listeners

The preventDefault() function is used to cancel the execution of the listener function of an event. The function is used with the eventObj parameter—eventObj.preventDefault()—of the listener function.

For example, if you were to use this function with the beforeRender event of the chart, the result will be that the chart won’t render.

Removing Event Listeners

To curb needless memory consumption by charts on a page, it is advisable to remove all event listeners that are not required.

The two functions that you can use to remove event listeners are:

• removeEventListener()
• detachHandler()

The removeEventListener() Function

Event listeners attached globally on all charts can be removed by calling the removeEventListener() function on the FusionCharts object.

The removeEventListener() function takes the following two parameters:

The detachHandler() Function

The detachHandler() function is used to remove/stop a listener from listening to an event.

One of the applications of this function is to restrict listening to an event only for the first instance of trigger.

The code snippet below shows how you can use this function:

...
var func = function (eventObj) {
   console.log("Data was updated for the first time in chart");
   // Call detachHandler to stop listening to this event
   eventObj.detachHandler(a, b);
};

revenueChart.addEventListener("dataUpdated", func);

revenueChart.addEventListener("renderComplete", func);
...

The above code executes the listener when the dataUpdated event is triggered for the first time; after this execution, the listener detaches itself from the event.