ColdFusion Article

Introducing the cfchart tag
You create dynamic charts and graphs in ColdFusion MX with three new tags: cfchart, cfchartseries, and cfchartdata.

You can think of the parent tag, cfchart, as defining the information about the container into which the chart will be placed. It defines the chart's size and colors, information about how to present the x and y axis, and other formatting and high-level graph behavior options.

Within the container that you described in the cfchart tag, you place any number of "series" of data. These are the sets of numbers that will be graphed. For example, one series may be your company's sales figures, by month, for a given calendar year. A second series in the same graph may be the sales figures for a prior year. Each of these series is defined with the cfchartseries tag.

You have two options in defining from where the data in the series will come. You can specify that a series is populated with the data in a query, typically from running a cfquery tag previously on the page, or you can code each individual point in the series with cfchartdata tag.

So with these three tags, a simple chart is structured as follows:

<cfchart>
    <cfchartseries query="..."/>
    <cfchartseries>
	<cfchartdata/>
	<cfchartdata/>
	(...)
   </cfchartseries>
</cfchart> 

Even with no attributes specified, you can see the basic architecture of the chart from the combination of tags above:

Creating a basic chart
Using the example applications database that ships with ColdFusion MX, you can create a chart that will show a company's hiring trends over a two-year period.

Query the database
To begin, query the example application database to get a count of employees by department who were hired in 2002.

The query displays in a tabulated format, as follows.

This information will be turned into a graph next.

Create the chart
You are now ready to create the basic chart and plot its single data series. To do so, use the following steps:

Here it is - a simple bar chart of each department's hiring for 2002, as follows:

Of course, there are a number of problems with the chart:

You will now use some of the attributes of the parent cfchart tag to better format the basic chart's appearance.

Add the following attributes to the top cfchart tag:

     xAxisTitle="Department"
     yAxisTitle="New Hires"
     scaleFrom="0"
     scaleTo="8"
     gridlines="5"

The cfchart tags should now look like this:

   <cfchart
       xAxisTitle="Department"
       yAxisTitle="New Hires"
      scaleFrom="0"
      scaleTo="8"
      gridlines="5">

    <cfchartseries type="bar"
		query="chartData2002" 
		itemColumn="DepartmentName"
		valueColumn="dptCount"
		seriesLabel="2002 Hiring"/>

   </cfchart>

This displays the following chart:

The cfchart tag has more than 30 attributes so it's best to refer to the ColdFusion MX documentation book "Developing ColdFusion MX applications with CFML" for a thorough understanding of all of the tag's power. Here, with just these 5 attributes, you have significantly changed the chart's appearance. The scaleFrom, scaleTo, and gridlines attributes allow you to control the display of values on the "y" axis and the two title tags allow better explanation of the chart to your end-users.

Adding additional series
What you have coded so far could have been accomplished using the graphing features first introduced in ColdFusion 5. One of the most significant improvements in ColdFusion MX is the ability to chart many series within the same chart. This was not possible in ColdFusion 5 and allows you to create far more complex illustrations of business data.

Next, add a second query to get data for the 2000 year and add a series for it to the cfchart tag.

Each series has a different color and the top of the graph displays a legend indicating the color of each series. Notice, too, that as you move your mouse over any of the bars in the graph, a pop-up window displays. This "tip" box can be enabled or disabled and customized and displays the details about each item in the series.

For the last step in this tutorial, you will use the cfchartdata tags to add a third series that contains data that did not come from a database. This can be helpful for charting data from other sources or for looping over a query and doing some formatting or calculation on each item before graphing it.

The following chart displays:

Notice that the type attribute was changed from "bar" to "line" for this series. In ColdFusion MX, charts can combine any of the types from series to series (with the exception of "pie" charts which can only display a single series of data). As you add series to the chart, they will be "layered" in the order of the cfchartseries tags within the cfchart tag.

For example, if this chart were to be displayed in 3D format (with the show3d="yes" attribute value in the cfchart tag), the 2002 series would be in the front, followed by 2001 and, finally, Projected 2003 in back. If you wanted the 2003 line to "lay over" the other bars, simply move its cfchartseries tag prior to the other chartseries tags within the cfchart start and end tags.

Conclusion
This tutorial has shown you the basic architecture of charts and graphs in ColdFusion MX, how to add and layer multiple series of data, and some basics about chart appearance attributes. Future tutorials will show you how to get even more out of these new tags by integrating with Macromedia Flash MX, enabling your users to drill-down to detail pages from your charts, save charts to disk for ultra-fast delivery in your applications, and more. Of course, if you can't wait, refer to the ColdFusion documentation book, "CFML Language Reference" for the cfchart and cfchartseries tags, and in the documentation book "Developing ColdFusion MX applications with CFML."