FusionCharts and Javascript – The Chemistry

FusionCharts Suite shares a great chemistry with Javascript. What does this mean for you? Quite a lot actually. You can combine the two of them to:

1. Create comprehensive sales reports: Show a chart at the top with summarized sales info for say 5 years. Then allow the user to click on any of these years for more details in the same page, without any page refreshes. See a demo.
2. Provide buttons for exporting/printing charts outside the chart area: FusionCharts allows you to export the charts as JPEG/PNG/PDF (one at a time or all of them in a page at once) and also print them with a single click. Using Javascript, you can provide buttons outside the chart area for doing the same thus providing a very friendly UI. See a demo.
3. Build flight selectors: Give the user a map and show all the possible routes he can fly. When he clicks on a particular route, show him all the flights for that route. Wouldn’t it save a lot of time otherwise wasted in selecting a city in the ‘From’ and then again in the ‘To’ field. See a demo.
4. Track events like loading/rendering/data loading of charts: Using Javascript you can track whether a chart has been loaded and rendered, and the same for the data as well. Also, you can check if some error occurred during either of these processes in which case you can call suitable routines to either correct the error or display it.
5. Get data/attributes from chart: You can retrieve the entire data from the chart either in CSV or XML format. You could also retrieve individual attributes of the chart in Javascript.

This list is by no means a comprehensive list of the things you can do with FusionCharts and Javascript combined. It is meant to give you a small idea of things and fire up your imagination before we go behind the scenes. Also, you might appreciate that since FusionCharts and Javascript have infinite possibilities together, it will not be possible to discuss everything at length in this post itself. While we have provided relevant links for more information wherever it is apt; whenever you need more info on anything, please check out the section FusionCharts and Javascript in our online documentation. Ready? Here we go.

Basics

The FusionCharts download package consists of the chart swfs and the FusionCharts Javascript class called FusionCharts.js among other things. These are the only 2 resources we need to concern ourselves with to explore the power of FusionCharts and Javascript. The chart swfs as is evident are the individual chart files. FusionCharts.js is the FusionCharts Javascript class which allows easy embedding of charts in the webpages without the cryptic <object> and <param> tags. Security Issues: Adobe Flash Player, by default, restricts SWF files on local filesystem to make any JavaScript class, or vice-versa to protect the end user from “evil” SWFs. You can get around this by running the Javascript code either from the server (either remote or localhost) or by configuring the Flash Player to allow SWFs present in specific folders to raise JavaScript class by adding the folder to  http://www.macromedia.com/support/documentation/en/flashplayer/help/settings_manager04.html Now that we are done with the securty issues, let us take an example straightaway to understand how the chart swf and FusionCharts.js act in conjunction. This example illustrates 3 concepts:

1. How to embed a chart in a webpage using the simple Javascript embedding technique made possible by FusionCharts.js instead of using the cryptic <object> and <param> tags?
2. How to make use of the APIs exposed by the chart? In this example, we will make use of the setDataXML API to set the data for the chart.
3. How to track events raised by the chart? Here, we will display an alert box when the chart has finished rendering, using the FCRendered_event.

Don’t worry if you can’t make head or tail of the APIs and events we are talking about – we will discuss them in details later on. So the HTML for the page having the chart embedded in it would be:

FusionCharts

In the above code, we are first creating a Column3D chart using FusionCharts JavaScript class. We set the DOM ID of the chart as chart1Id. It is this ID using which the chart will now be recognized in the HTML page. You need to make sure that each chart on the page gets a different ID, else the browser would start behaving weirdly, to say the least. The FusionCharts constructor function, which helps you embed a chart easily using Javascript looks as under:

 var chart1 = new FusionCharts("../../FusionCharts/Column3D.swf", "chart1Id", "400", "300", "0", "1");

The parameters passed to it in order are: URL of the swf file of the chart type, its DOM ID, chart width and height, debugMode and registerWithJS – both of which accept boolean values. To register the chart with JavaScript, we set the registerWithJS parameter to 1. Now, we’ve provided a basic XML data document to the chart using its setDataXML method. Finally, we render the chart, and track the same to display an alert box when the chart has finished rendering and raises the FC_Rendered event.

Events exposed by the chart

Now that we have a basic grasp of things, let us take a look at the events that FusionCharts v3.1 exposes. Barring the first 2, everything has been newly introduced in FusionCharts v3.1:

• FC_Loaded(DOMId): Raised when the chart SWF has finished downloading in the user’s browser. Typical Use: To hide any loader components that you might have on your page.
• FC_Rendered(DOMId): Raised when the chart has finished rendering. Typical Use:    To invoke any further JavaScript methods on chart, or to change the data of chart.
• FC_DataLoaded(DOMId): Raised when the data of the chart has finished loading – both in dataXML or dataURL method. Typical Use: To further process data in any other components in your page.
• FC_DataLoadError(DOMId): Raised    when there was an error in loading data from the specified URL
• FC_NoDataToDisplay(DOMId): Raised when the XML data loaded by the chart didn’t contain any data to display
• FC_DataXMLInvalid(DOMId): When the XML data loaded by the chart was invalid (wrong XML structure)

The last 3 events are typically used to show an error message to the user, or to take a corrective measure. All the events can be tracked the same way as the FC_Rendered event was tracked using the DOMId of the chart in the example earlier.

Javascript APIs exposed by the chart

All the charts in the FusionCharts expose a number of APIs which allow you to print the chart, export the chart as image/PDF, get an attribute or the entire data of the chart and the like. These APIs are not a part of FusionCharts.js, but built into the chart swfs themselves and as such, you do not need to include FusionCharts.js in your HTML code to make use of these APIs. The APIs exposed by all charts in FusionCharts with their respective functions are:

• setDataURL(strDataURL:String): Changes the data of the chart to the new specified URL. The URL has to be relative to the chart.  More details here.
• setDataXML(strDataXML:String): Changes the data of the chart to the specified XML string. More details here. http://www.fusioncharts.com/developers/documentation/Contents/JS_setDataXML.html
• print(): Prints the chart. More details here.
• exportChart(exportSettings: Object): Calls the export chart routine to save the chart as PDF/image. To get more details on this, pleas check out the Exporting as Image/PDF section in the online documentation.
• getXML(): Returns the XML data of chart as string. More details here.
• getChartAttribute(attrName: String): Returns the value of the attribute as specified in chart’s XML data > <chart> element. More details here.
• signature(): A string representing the signature of SWF. For FusionCharts v3 charts, it’s FusionCharts/3.1
• hasRendered(): A boolean value indicating whether the chart has rendered. Boolean value indicating whether the chart has finished rendering
• getDataAsCSV(): Returns the data of chart as CSV string. More details here.

Except the first 2 APIs, all the other APIs have been newly introduced in FusionCharts v3.1. Now that you know about the tremendous chemistry that FusionCharts shares with Javascript, make the most out of it. With this post concludes the How to get the most out of v3.1 series. We hope this indeed helps you get the best out of our products. If there is any feature you want us to go into further details, just let us know in the Comments section and we will be onto it.