FusionCharts Beginner's Guide: The Official Guide for FusionCharts Suite

You have now successfully downloaded FusionCharts XT and extracted it in the FusionCharts Installation Folder. We will soon learn how to use these files to build charts. Before that, let us quickly explore the contents of the FusionCharts package.

Within the FusionCharts Installation Folder, you will find multiple folders. Some of the folders are internal folders used to store documentation and gallery files, for example, Contents, Gallery, and so on. The folders that you will mostly use are Charts, Code, SourceCode, ExportHandlers, and the Tools folder for the following purpose:

The FusionCharts Installation Folder also contains three files in the root folder:

When you run Index.html, you will see a page similar to the following screenshot:

When you click on the Documentation link, it opens the documentation for FusionCharts XT, as shown in the following screenshot:

This documentation is an exhaustive resource for FusionCharts including sections for beginners, chart parameter lists, API references, and sections on advanced charting. In this book, we will not repeat, but rather refer to the APIs and parameters explained in the documentation.

From Index.html, you can also explore all the chart types present in FusionCharts XT by clicking on Chart Gallery. It presents a list of chart types and multiple examples for each, as shown in the following screenshot. We recommend you spend some time exploring this, as this is a good learning resource to get a real-world feel of the charts and understand what you can create once you are familiar with FusionCharts.

The Live Demos section, accessible from Index.html, lets you explore sample dashboards and examples created using FusionCharts—both offline and online.

Now that you have had a taste of what FusionCharts can do for you, it is time to create your own chart, your first chart using FusionCharts.

Fundamentally, for each chart you build, you should ask yourself the following questions to ensure that the chart serves a meaningful purpose, as opposed to just being a fancy object on the page:

For our first chart that we build, Harry is the end user. This chart lets him compare the revenues of this year against the last two years. We would plot this data on a 3D Column chart, as Harry uses this to compare the revenues instead of seeing the overall trend. Had Harry wanted to see the trend of revenues over multiple years, we would have used an area or line chart. Also, to keep things simple, we will build this as a standalone chart.

Thereafter, technically, there are three steps to build a chart using FusionCharts:

Let us cover them one-by-one.

You just installed FusionCharts. It involved copying of all the SWF and JavaScript files of FusionCharts, which are the FusionCharts Core files. If you intend to plot just a subset of chart types, you can select only those SWF files and paste them here. However, copying all files makes it easier in the future whenever you need to create a new chart type in your application. Each SWF file is used to plot a particular type of chart in Flash and the name of the file represents the chart type. You can find the complete list of charts in FusionCharts Documentation | Introduction | List of Charts. For our first chart, we are going to use Column3D.swf to plot a 3D Column chart.

The FusionCharts folder also contains six JavaScript files that aid in embedding and configuring charts, along with rendering them in JavaScript when viewed on devices that do not support Flash. These files are as follows:

While creating your chart, as you will soon see, you just need to include FusionCharts.js in your page. The other files such as FusionCharts.HC.js, FusionCharts.HC.Charts.js, and jquery.min.js are dynamically loaded by the code in FusionCharts.js.

With the basic setup in place, let us focus on the data for our chart.

Here, we have encoded the data, as shown in the following table, to an XML format supported by FusionCharts:

Each chart in FusionCharts is powered by data. This data could be static and hand-coded as we will build in this example, or dynamically generated by live scripts that are connected to databases or web services which we will explore later in Chapter 6, Integrating with Server-side Scripts. FusionCharts can accept this data in two formats—XML and JSON. Both are commonly used formats for data exchange on the Web, with XML being easy on the human eyes.

The XML format that we just created is called single-series XML in FusionCharts parlance, as we are plotting just one series of data. Later in this chapter, we will explore multi-series charts that let you compare more than one series of data, for example, revenue split across Food and Non-Food products for each year across last three years.

All FusionCharts XML files start with the<chart> element. The attributes of the<chart> element help you configure the functional and cosmetic properties of the chart. In our example, we have defined the chart caption, subcaption, axis titles, and the currency prefix for numbers on the chart, as in the following line of code:

<chart caption='Harry&apos;s SuperMart' subcaption='Revenue by Year' xAxisName='Year' yAxisName='Amount' numberPrefix='$'>

For each chart type, there are hundreds of optional attributes that you can define. If these are not defined, the chart assumes the default values for each of them.

Each row of data to be plotted on the chart is represented by the<set> element. The label attribute defines the text label for each data point, and the value attribute defines its numerical value to be plotted. There are additional attributes that can be defined for the<set> element, for example, user-defined colors, which we will explore in later chapters. An important thing to note is how the $ prefix or comma separators have been stripped off the revenue numbers, before encoding them as a value for the<set> element, that is, $1,487,500 has been converted to 1487500, as shown in the following line of code:

<set ... value='1487500' />

This is necessary as FusionCharts can interpret only standard numeric values.

With both the basic setup and data in place, we are just one step away from seeing our chart live—writing the HTML and JavaScript to embed this chart, which we will do next.

You just created your first chart, that's what happened! This chart renders using Adobe Flash on devices that support it, and automatically switches to JavaScript rendering on devices such as iPads and iPhones. The beauty of the solution is that no additional code or configuration is required to do this.

Let us break down our HTML and JavaScript code into digestible chunks. To create charts using FusionCharts in your page, you first need to include the FusionCharts JavaScript library (FusionCharts.js), as in the following lines of code:

<script type="text/javascript" src="../FusionCharts/FusionCharts.js">
</script>

Note that you only need to include FusionCharts.js in your code. The other files required for FusionCharts, namely FusionCharts.HC.js, FusionCharts.HC.Charts.js, and jquery.min.js are dynamically loaded by code in FusionCharts.js.

Next, we create a DIV as a placeholder where the chart would be rendered. We give the DIV an ID—chartContainer. This is done using the following code:

<div id="chartContainer">FusionCharts will load here!</div>

The DIV carries a placeholder text FusionCharts will load here! which will be displayed if there is an error in your JavaScript code, or FusionCharts.js or the chart SWF file could not be loaded. If you see this text instead of the chart, you know what to fix.

Following this, we initialize a chart by invoking the FusionCharts JavaScript constructor, using the following code:

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

To this constructor, we pass the following parameters in order:

<script type="text/javascript">
<!--var myChart = FusionCharts.render ("../FusionCharts/Column3D.swf", "myChartId", "400", "300", "chartContainer", "Data.xml"); // -->
</script>

Once the chart is constructed, we tell the chart where to source data from. We use a relative path to Data.xml, as it is stored in the same folder.

myChart.setXMLUrl("Data.xml");

If you recall, FusionCharts accepts data in two formats — XML and JSON — either provided as a string or a URL that points to the data file. In our example, we have used XML as the data format, which is stored in Data.xml. So, we use the setXMLURL() function to pass the URL of the XML data file to the chart.

Finally, to render the chart in the DIV that you had earlier created, you invoke the render() function and pass to it the ID of the DIV.

myChart.render("chartContainer");

Do remember that each chart and DIV needs to have its own unique ID.

What to look for if your chart is not rendered?

If you do not see any chart, there could be multiple reasons behind it. You should check for the following, based on what you see in your browser:

What do you currently see instead of the chart?	Corrective measures you should take
"FusionCharts will load here!" text that you had placed in the container DIV	Check whether the FusionCharts folder is present in the LearningFusionCharts folder and contains all JavaScript files required for FusionCharts. Check whether you have provided the correct relative path to FusionCharts.js in the page FirstChart.html. Check for errors in your JavaScript code that you have written to embed the chart. Use the browser's developer tools to check this. Ensure that you have given different IDs for container DIV, chart JavaScript variable and the chart object in the constructor.
Empty white area instead of the chart	Check whether you have copied Column3D.swf to the FusionCharts folder. Check whether the relative path provided to Column3D.swf in FusionCharts constructor is correct.
"Error in loading data"	Check whether Data.xml is present within the FirstChart folder Check whether the path specified to Data.xml is correct in the setXMLUrl() method.
"Invalid data"	Check for the validity of XML data in Data.xml by opening it in a browser or an XML editor. Or, you can also switch the debug mode of chart to ON by changing the last but one parameter in constructor to 1. That will highlight the error in XML, as shown in the following screenshot:

With these measures, you should be able to locate the error and get your chart working. Before we move ahead to explore the other aspects of FusionCharts, let us understand how FusionCharts automatically switches between Flash and JavaScript mode.

By default, FusionCharts renders its charts using Adobe Flash. However, as you have seen earlier, when you view the chart on iPads or iPhones, FusionCharts automatically switches to JavaScript rendering, as Flash is not supported on those devices. This is internally checked by FusionCharts.js, and the auto-loaded files FusionCharts.HC.js, FusionCharts.HC.Charts.js, and jquery.min.js then aid in rendering the chart using JavaScript, using the same datasource and configuration.

FusionCharts also provides an option to entirely skip Flash rendering and use JavaScript as the default rendering, irrespective of the device. This feature can be very nifty for developers who want to develop JavaScript-only applications or even frameworks. Let us quickly see how to attain that.

You just converted the previous chart to a pure JavaScript chart, irrespective of the device it is now viewed on. The following snippet of code instructs FusionCharts to switch the rendering mode to JavaScript:

FusionCharts.setCurrentRenderer('javascript');

If your page contains multiple charts, this setting applies to all such charts that are defined after this line of code. Hence, if you declare this at the beginning, all the charts in the page will render using JavaScript. You would not need to declare the same for each chart in the page.

In this example, you created a standalone Column 3D chart. How about inching towards building a complete dashboard? To do so, convert the existing chart to a Column 2D chart and add the following three charts to this page. In addition, specify different width and height for each chart to accommodate the amount of data it presents, and also place them in order of importance of the chart to Harry.

All these charts use the same single-series XML format that you had earlier created. Remember to provide a different ID for each chart and its container DIV. Also, do not forget to encode special characters such as& (ampersand) or' (apostrophe) in XML.

Once you are done, let us explore the other way to provide XML data to FusionCharts—as a string, instead of providing a URL, for example, Data.xml.

You just used the Data String method of FusionCharts to power up your chart using XML data embedded in the page, instead of reading it from Data.xml. This was done by invoking the setXMLData() method on the chart instance.

myChart.setXMLData("<chart caption='Harry&apos;s SuperMart' subcaption='Revenue by Year' xAxisName='Year' yAxisName='Amount' numberPrefix='$'>\ <set label='2009' value='1487500' />\ <set label='2010' value='2100600' />\ <set label='2011' value='2445400' />\ </chart>");

The entire XML string is passed to this method. Note how we are using the \ characters in JavaScript to split the XML data string into multiple lines for enhanced readability. Make sure there are no trailing spaces, when using this approach.

You can also define a JavaScript string variable, store XML data in it, and then assign the variable reference to the chart instance, as shown in the following code snippet:

<html>
<body>
<div id="chartContainer">FusionCharts will load here!</div>
<script type="text/javascript">
<!-- var strData =
"<chart caption='Harry&apos;s SuperMart' subcaption='Revenue by
Year' xAxisName='Year' yAxisName='Amount' numberPrefix='$'>" +
"<set label='2009' value='1487500' />" +
"<set label='2010' value='2100600' />" +
"<set label='2011' value='2445400' />" + "</chart>";
var myChart = new FusionCharts("../FusionCharts/Column3D.swf",
"myChartId", "400", "300", "0", "1" );
myChart.setXMLData(strData);
myChart.render("chartContainer");// -->
</script>
</body>
</html>

In the previous example, we had stored the entire XML string in the variable strData, and then passed its reference to the setXMLData() method, instead of the XML string directly.

When using this method to provide data, if your chart is not working or reporting Invalid data, check for the following:

Now that you are familiar with both the ways of providing XML data to FusionCharts, let us explore the other data format supported by FusionCharts—JSON.

Using the FusionCharts Data Format Conversion Tool, you just converted the previous XML data into JSON format. It reads as in the following code snippet:

{
"chart": {
"caption": "Harry's SuperMart",
"subcaption": "Revenue by Year",
"xaxisname": "Year",
"yaxisname": "Amount",
"numberprefix": "$"
},
"data": [
{
"label": "2009",
"value": "1487500"
},
{
"label": "2010",
"value": "2100600"
},
{
"label": "2011",
"value": "2445400"
}
]
}

Similar to XML, the chart object contains attributes that let you configure functional and cosmetic aspects of the chart.

In the most general form, chart attributes represent the following JSON format:

"attributeName" : "Value"

For example,"xAxisName" : "Year"

The attributes can occur in any order and values can be specified either using double quotes or single, for example, xAxisName:'Year'. However, you need to ensure that the same attribute is not defined twice for any element, as it results in an invalid XML.

Next, the array data contains all the data points to be plotted on the chart. For example, in XML, label attribute for each data point defines its text label, and the value attribute represents its numerical value. Each element in the data array is an unnamed object defined in the following format:

{ "label: "Jan", "value" : "17400", "otherAttribute" : "value"}

With the JSON format understood, let us also look at how to use the setJSONUrl() and setJSONData() methods.

You just configured your chart to use JSON data as URL, instead of XML. If you do not see a chart, however, your browser might be restricting JavaScript to load local files. In that case, you will have to switch to the JSON Data String method, as explained in the next section.

You changed the setXMLData() function to the setJSONData() function and provided JSON data instead of XML data. Also, note how the apostrophe in Harry's SuperMart was escaped in JavaScript so as to form Harry\'s SuperMart. Otherwise, there would have been a conflict of quotes leading to invalid JavaScript syntax.

You can also provide the JSON data to the setJSONData() method as an object, instead of a string, as shown in the following code:

<html>
<body>
<div id="chartContainer">FusionCharts will load here!</div>
<script type="text/javascript">
<!-- var myChart = new FusionCharts("../FusionCharts/Column3D.swf", "myChartId", "400", "300", "0", "1" );
myChart.setJSONData({
"chart": {
"caption": "Harry\'s SuperMart",
"subcaption": "Revenue by Year",
"xaxisname": "Year",
"yaxisname": "Amount",
"numberprefix": "$"
},
"data": [{
"label": "2009",
"value": "1487500"
},{
"label": "2010",
"value": "2100600"
},{
"label": "2011",
"value": "2445400"
}]});
myChart.render("chartContainer");// -->
</script>
</body>
</html>

Here, we have converted the JSON string to a JavaScript object by removing the enclosing string quotation marks and even the \ character that was used for concatenating the string distributed across multiple lines. And that does it all!

Bingo! You are now adept with the basics of FusionCharts. You have learned how to create a FusionCharts, provide XML or JSON data as either URL or string, and even render the chart using pure JavaScript. Now, we are all set to explore additional charts in FusionCharts. First, we will create a chart with more than one series of data, called a multi-series chart in FusionCharts parlance.

In MultiSeriesChart.html, we have changed the SWF file from Column3D.swf to MSColumn3D.swf to render a multi-series chart. FusionCharts uses separate SWF files to plot charts with single series of data (single-series) and those with more than one (multi-series). Names of SWFs that plot multiple series start with a prefix of MS. We have also pointed XML URL to the newly created MSData.xml, which contains data in multi-series format for this chart, in the setXMLUrl() method. These are the only changes required in the web page.

The bulk of changes are in the XML data file to adapt it to the multi-series format. Let us review them. The multi-series chart XML begins with the<chart> element, similar to single-series and all the other charts in FusionCharts. You can provide attributes for the<chart> element to configure the functional and cosmetic properties of the chart. In this example, building on top of our earlier single-series chart, we have introduced a new attribute rotateValues='1', that rotates the data values on the chart to accommodate more numbers. The other attributes remain the same.

Next, we have the<categories> element that is applicable when you are plotting multi-series charts only. Each child<category> element of the<categories> element represents an x-axis label (also called the data point's label). The label attribute of the<category> element lets you specify them as string values. In our chart, we are comparing the segment-wise sales for 2009, 2010, and 2011, and hence have them as x-axis labels.

<categories>
<category label='2009' />
<category label='2010' />
<category label='2011' />
</categories>

All that is now left to be defined is data for both the data series. Each series is represented by a<dataset> element and attributes of this element lets you specify a custom color for the series, and whether to show or hide data values. To define individual data points within a series, children<set> elements are added with a value attribute containing a data point value.

<dataset seriesName='Food Products'>
<set value='892500' />
<set value='1407400' />
<set value='1565000' />
</dataset>

The data point labels or x-axis labels in<category> elements are matched to their respective data point values in the<set> element, based on the order of the definition in XML, that is, the first<category> element provides the label for the first<set> element and so on. To plot a normal chart, the number of<set> elements within each<dataset> should be equal to the number of defined<category> elements.

The previous XML can also be used to plot a stacked chart where columns are placed on top of each other as opposed to side-by-side. The stacked charts are used when the constituents of a data series are relevant along with the sum of all such constituents. While these charts are suited for the comparison of sum, comparison of the constituents against each other is best portrayed by the multi-series chart. To build our stacked chart, we need to change the chart SWF to StackedColumn3D.swf. In the XML, we only make a small change to not rotate the data values by removing the rotateValues='1' attribute from the<chart> element. This results in a chart as shown in the following screenshot:

No. If you have more<category> elements than<set> elements in any data series, FusionCharts fails to find data for those additional<category> elements and plots an empty space on the chart for the missing data points. In contrast, if the number of<set> elements are more than the number of defined<category> elements, FusionCharts ignores them, as these data points do not have respective x-axis labels defined for them, and hence would be without context.

In real-life scenarios, you may have missing or non-existent data within a data series. FusionCharts provides a method for you to specify that. Let us consider an example.

Representing missing or non-existent data on the chart

Let us consider a hypothetical example of building this on top of our last example. What if Harry started selling food products only in 2010, when he added refrigeration capabilities? However, non-food products were still sold in 2009. Hence, we would need to tell FusionCharts that data for food products in 2009 is missing or nonexistent. This can be done by specifying an empty<set/> element as in the following XML:

<chart caption='Harry&apos;s SuperMart' subcaption='Revenue by Year' xAxisName='Year' yAxisName='Amount' numberPrefix='$' rotateValues='1'>
<categories>
<category label='2009' />
<category label='2010' />
<category label='2011' />
</categories>
<dataset seriesName='Food Products'>
<set />
<set value='1407400' />
<set value='1565000' />
</dataset>
<dataset seriesName='Non-Food Products'>
<set value='595000' />
<set value='693200' />
<set value='880400' />
</dataset>
</chart>

This instructs the chart to render an empty space instead of the column representing food-products in 2009, to indicate missing or non-existent data. This method of providing missing data is applicable to all charts in FusionCharts.

Note

Can missing data be replaced by providing zero values?

You might wonder that if there was no data for 2009, why could we not specify the value as 0. It would mean that Harry's SuperMart was not able to sell any food products in 2009, as opposed to the fact that it did not stock food products then. Both have different meanings and need to be visualized accordingly.

Now that you have an understanding of how to plot multiple series on a chart for comparison, let us consider an extension of multi-series charts—combination charts.

We just created a combination chart to compare the actual revenue of Harry's SuperMart to the projected revenues, which were set as a target. For a change, we have plotted it as a 2D chart using MSCombi2D.swf. The XML data is similar in structure to the multi-series chart. The three years that form the x-axis labels are provided as<category> elements. There are two data series in the chart, one representing the actual revenue, and the other, projected revenue. There are a few new attributes that we have added to the<dataset> element of the data series representing the projected revenue, as the following line of code:

<dataset seriesName='Projected Revenue' renderAs='Line' dashed='1' showValues='0' color='666666'>

The first attribute renderAs='Line' instructs FusionCharts to render this series as a line series. The other possible values are Column and Area for this chart. As this line in the chart reflects guidance of revenues, we have visually indicated this by plotting it as a dashed line using the attribute dashed='1'. Thereafter, we have turned off the display of the data values for this series using showValues='0' to avoid cluttering of too many data values. Finally, we have provided a custom color for this series using color='666666'.

Simple, isn't it? Let us now build the second type of combination chart, to compare the revenues versus units of products sold.

We just enabled Harry to compare the revenues of Harry's SuperMart for the last three years, along with the units sold. This chart gives him a perspective on how the revenues are affected by the units sold. Note how this chart has two y-axes, one on the left called primary axis, and one on the right called secondary axis. Each axis has its title defined using two new attributes of the<chart> element, PYAxisName for the primary axis, and SYAxisName for the secondary axis. The attribute YAxisName is not applicable to this chart as there is no common y-axis.

<chart caption='Harry&apos;s SuperMart' subcaption='Revenue and Units Sold by Year' xAxisName='Year' PYAxisName='Amount' SYAxisName='Units Sold' numberPrefix='$'>

The numberPrefix attribute gets applied to the primary axes. If we had to specify a number prefix for the secondary axes, we would use the attribute sNumberPrefix.

There are two data series in the chart, the first representing the revenue, and the other containing data on the units sold. The second series, representing quantity, has a new attribute parentYAxis='S' that lets you configure whether this data series is plotted against the primary axis (parentYAxis='P', by default) or the secondary axis (parentYAxis='S'). In our example, as the units sold is to be plotted against the secondary axis, on the right, we have set parentYAxis='S', the other attributes remaining the same as before.

<dataset seriesName='Units Sold' parentYAxis='S' renderAs='Line' showValues='0' color='666666'>

If you were using a 3D chart such as MSColumn3DLineDY.swf, the renderAs attribute is not required, as the chart can only plot columns on the primary axis and lines on the secondary. Just setting parentYAxis='Y' plots the data series as a line against the secondary y-axis.