FusionCharts v3 Documentation - Create your first chart

Creating your First Chart

To get you started with FusionCharts, we'll show you how to build a simple 3D column chart showing "Weekly Sales Summary" for an arbitrary month. Once completed, the chart would look as under (with animation and interactivity, which is not reflected by the image below):

Following steps are involved in creating the above chart:

Create a folder LearningFusionCharts on your hard-drive. We'll use this folder as the root folder for building all FusionCharts examples.
Create a folder named MyFirstChart inside the above folder. Inside MyFirstChart folder, create a folder named FusionCharts.
Copy Column3D.swf from Download Pack > Charts folder to FusionCharts folder.
Copy FusionCharts.js, highcharts.js and jquery.min.js files from Download Pack > Charts folder to FusionCharts folder.
Create an XML file » (Creating an XML file is as easy as creating a text file using Windows Notepad or any other text editor. It is actually a plain text file with extension - xml) in MyFirstChart folder with name Data.xml.

The code given below (left), is the XML-lized form of the sales data shown in the table (right). Copy the XML code to Data.xml file.

<chart caption='Weekly Sales Summary'
   xAxisName='Week' yAxisName='Sales' numberPrefix='$'> 
    <set label='Week 1' value='14400' /> 
    <set label='Week 2' value='19600' /> 
    <set label='Week 3' value='24000' /> 
    <set label='Week 4' value='15700' /> 
</chart>

Week	Sales
Week 1	$14,400
Week 2	$19,600
Week 3	$24,000
Week 4	$15,700

Create an HTML file weekly-sales.html in the same folder and copy-paste the code given below:

<html>
  <head> 	
    <title>My First chart using FusionCharts</title> 	
    <script type="text/javascript" src="FusionCharts/FusionCharts.js">
    </script>
  </head>   
  <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.setXMLUrl("Data.xml");
      myChart.render("chartContainer");
      
    // -->     
    </script> 	   
  </body> 
</html>

And that completes the recipe!

Open the file weekly-sales.html in a Web Browser » Internet Explorer, Firefox, Opera or Safari (Mac/iPhone/iPad/Windows) and you will see an animated Column 3D chart similar to the one below:

See it live!

Code examples discussed in this section are present in Download Package > Code > MyFirstChart folder.

Now that you've already rendered a chart, let's get behind the scenes and understand how FusionCharts renders charts in a web-page. Essentially, to create a chart, you need the following 4 items:

Chart SWF files : Each chart in FusionCharts is an SWF file that creates a specific type of chart. So, if you want to create 3D column chart, you'll need the SWF file called Column3D.swf. Similarly for creating a 3D pie chart you'll need Pie3D.swf. For the complete list of chart SWF files, refer to FusionCharts v3 Chart List. The chart SWF file is loaded and rendered using Adobe Flash player plug-in that is installed on your machine (more specifically, browser).
Chart data : FusionCharts data file contains both data for plotting, and cosmetic/functional configuration for the chart. FusionCharts accepts data in XML and JSON format. The XML or JSON data document can either be produced manually or generated using server-side scripts that are connected to your databases or live data sources. In the above example, we have used a hand-coded XML file for plotting the chart.
JavaScript class files : These are also present in the Charts folder in the root of the Download Package. The JavaScript class files help in embedding the chart SWF files into a web page, and also helps in rendering JavaScript (HTML5) fallback charts. Additionally, it provides a JavaScript interface for controlling the chart.
HTML wrapper file (or a dynamic web page): The HTML wrapper file is where the charts are rendered. This file contains the code which integrates all other components (discussed above) to produce the charts.

What happens if Flash player is not available?

In case Flash Player is not available on certain devices (like iPad/iPhone), FusionCharts JavaScript library automatically renders the same chart using JavaScript. For iPhone/iPad you do not need to modify anything to enable this. However, for other browsers without Flash Player or if you wish to use pure JavaScript-only charts, you can also explicitly render JavaScript charts.

Let's take a closer look at the data and its XML form:

<chart caption='Weekly Sales Summary'
   xAxisName='Week' yAxisName='Sales' numberPrefix='$'> 
    <set label='Week 1' value='14400' /> 
    <set label='Week 2' value='19600' /> 
    <set label='Week 3' value='24000' /> 
    <set label='Week 4' value='15700' /> 
</chart>

Week	Sales
Week 1	$14,400
Week 2	$19,600
Week 3	$24,000
Week 4	$15,700

Basically, what we've done above can be listed in the following points:

We've created the root <chart> element, with a few attributes to define caption, axis titles and number prefix character
For each data row (in table), we've created a <set> element. label attribute of this element represents the week name and value attribute represents the sales value for that week. This is the entire data that we wish to plot on the chart. Note how we've removed the number prefix ($) and comma separators from each value before specifying it in XML as <set value='14400'>. FusionCharts needs the numbers to be in pure numeric format when specified in XML or JSON.

Just as a measure to check if the XML document is structurally valid, open the file in your browser. You should be able to see the XML data document in a formatted way, without any errors.

For creating manual XML data, you can use the visual XML Generator Utility, which converts tabular data into XML. For instructions on using the XML Generator Utility refer to "Guide for General Users" section.

Note that you can also provide chart data in JSON format. View an example of JSON data here. Or, to learn more about FusionCharts JSON data format, please go through FusionCharts data formats > JSON section.

In the HTML wrapper file (or your web page), the shots are called by the included JavaScript class file FusionCharts.js. Let's take a second look at the HTML code to gain an understanding of how it works.

<html>
  <head>
    <title>My First chart using FusionCharts</title>
    <script type="text/javascript" src="FusionCharts/FusionCharts.js">
    </script>
  </head>
  <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.setXMLUrl("Data.xml");
      myChart.render("chartContainer");

    // -->
    </script>
  </body>
</html>

In the very beginning, the JavaScript class file FusionCharts.js is included into the HTML using the code shown below. FusionCharts.js is smart enough to automatically load the other required JavaScript files - jquery.min.js and highcharts.js on-demand.

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

Next, a HTML DIV with id chartContainer is created in the body of the page.

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

Now comes the essential part, which instantiates the chart. This is called the chart constructor.

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

Here, myChart is the name of the JavaScript object (variable) that contains reference to the chart.

The following parameters are passed on to the MyChart object:

URL of SWF file of the chart type that we intend to use. FusionCharts/Column3D.swf in this example as Column3D.swf is the name of SWF and it is contained in a relative path inside FusionCharts folder.
ID of the chart. You can give any ID for the chart. Just make sure that if you're using multiple charts in the same HTML page, each chart should have a unique ID. In our example above, we provid "myChartId" as the ID.
Required width and height of the chart. When providing in pixels, just give the numeric value (without px).
The last two parameters are debugMode and registerWithJS. debugMode is set to "0" (off) normally except for when debugging is required. registerWithJS allows the chart and JavaScript to interact with each other. This parameter is deprecated and is always set to "1" (on) internally. We'll explain these parameters later.

The code below provides the reference (relative URL) of chart data file (XML in this case). The path of the XML file is set using setXMLUrl() function as shown below:

myChart.setXMLUrl( "Data.xml" );

The code sample above uses Url of static XML file. Ideally, you would NOT use a physical data file. Instead you'll have 'your own server side scripts to use dynamic data and build XML. You can always provide the Url of the script to virtually relay the dynamically built data.

Finally, the render() method is called and the ID of HTML DIV, where the chart is meant to be rendered, is provided. This line of code renders the desired chart inside the DIV.

myChart.render( "chartContainer" );

Existing users : You might be wondering what happened to the functions like setDataURL()which you have already been using in your application. Yes - although deprecated, it will continue to work without any problem.

Since v3.2, FusionCharts also provides alternate methods of declaring and rendering a chart using JavaScript.

You can use a compact single-line of JavaScript (instead of the three lines we saw in the above sample) to render a chart as shown below:

<html>
  <head> 	
     <title>My First chart using FusionCharts - Compact Rendering Method</title> 	
	  <script type="text/javascript" src="FusionCharts/FusionCharts.js"></script>
  </head>   
  <body>     
     <div id="chartContainer">FusionCharts will load here!</div>          
	  <script type="text/javascript"><!--

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

See it live!

The above code uses the static render function of the global FusionCharts object. This function takes all required parameters to render a chart like the chart SWF, chart ID, width & height of chart, div ID where chart will be rendered and reference to chart data.

There are additional ways of rendering a chart as well, which have been explained in Creating charts page in "FusionCharts and JavaScript" section.

If for any reason, you do not see a chart, run through the following checks:

If you see an endless loading progress bar in your browser, or if the right click menu (right click at the place where the chart is supposed to be) shows "Movie not loaded", check the following:

Have you pasted the chart SWF files in FusionCharts folder of MyFirstChart folder?
Have you provided the SWF path properly in your weekly-sales.html page?
Do you have Adobe Flash Player 8 (or above) installed for this browser?
Have you enabled your browser to show ActiveX/Plugin controls? Normally, all browsers are Flash-enabled, but sometimes security settings can disable execution of Active X/Plugin controls.

If you get an "Error in Loading Data" message, check the following:

Whether Data.xml is in the same folder as the weekly-sales.html HTML file?
Whether Data.xml is named as Data.xml and not Data.xml.txt, as many basic text editors append .txt after the file name?

If you get an "Invalid XML Data" message, it means that the XML data document is malformed. Check it again for common errors like:

Difference in case of tags. <chart> should end with </chart> and not </Chart> or </CHART>
Missing opening/closing quotation marks for any attributes. e.g., <chart caption=Weekly Sales Summary' should be <chart caption='Weekly Sales Summary'
Missing closing tag for any element

To check whether your final XML is ok, open it in your browser and you'll see the error.

If you only get "FusionCharts will load here!" text shown, check the following:

Have you pasted the FusionCharts.js, jquery.min.js and highcharts.js files in FusionCharts folder of MyFirstChart folder?
Have you included and provided the path of FusionCharts.js properly in your weekly-sales.html page?
Are there any JavaScript syntax or runtime errors that might have halted the execution of FusionCharts functions?
Have you given different names for the chart's JavaScript variable and chart's ID?