Advanced Charting

Beyond basic charts and formatting (explicit and via skins), ColdFusion supports advanced graphing and charting options that are all exposed via tags.

Using Multiple Data Series

To use multiple data series in a single chart, simply include multiple <cfchartseries> tags. The additional <cfchartseries> tags can each display different columns from the same query, or they can display information from different queries or data sources altogether, as seen in this example:

 <!--- This defines the size and appearance of the chart ---> <cfchart chartwidth="750"          chartheight="450"          yaxistitle="Budget"          seriesplacement="cluster">  <!--- Budget chart --->    <cfchartseries type="horizontalbar"                  seriescolor="99ff99"                 serieslabel="Amount Budgeted:"                 query="chartquery"                 valuecolumn="amountbudgeted"                 itemcolumn="movietitle">  <!--- Expenses chart --->    <cfchartseries type="horizontalbar"                  seriescolor="ff4444"                 serieslabel="Actual Expenses:"                 query="chartquery"                 valuecolumn="expensetotal"                 itemcolumn="movietitle"                 paintstyle="light"> </cfchart> 

This example defined to series of the same type, but types can be mixed as needed.

NOTE

You can't combine pie charts with other types of charts. Any <cfchartseries> tags that try to mix pie charts with other types will be ignored.

Drilling Down from Charts

The <cfchart> tag supports a URL attribute that you can use to create clickable charts, where the user is able to click the various data points in the chart to link to a different page (possibly another chart, creating a drill-down effect).

To create a clickable chart, simply add a URL attribute to the <cfchart> tag. When the user clicks one of the data points in the chart (the slices of a pie chart, the bars in a bar chart, the points in a line graph, and so on), he will be sent to the URL you specify. So, if you want the browser to navigate to a ColdFusion page called details.cfm when a chart is clicked, you would use url="details.cfm". You can use any type of relative or absolute URL that would be acceptable to use in a normal HTML link.

In order to make the detail page dynamic, though, it will need to know which data point the user clicked. To make this possible, ColdFusion allows you to pass the actual data that the user is clicking as URL variables. To do so, include any of the special values shown in Table 20.6 in the url attribute. ColdFusion will create a dynamic URL for each data point by replacing these special values with the actual data for that data point.

Table 20.6. Special Values for Passing in <cfchart> URLs

VARIABLE	DESCRIPTION
$value$	The value of the selected row (that is, the value in the valuecolumn attribute of the <cfchartseries> tag for the data point that was clicked). This is typically the value that you are most interested in passing in the url.
$itemlabel$	The label of the selected row (that is, the value in the itemcolumn for the data point that was clicked).
$serieslabel$	The series label (that is, the value of the serieslabel attribute of the <cfchartseries> tag). It is usually necessary to include this value in the URL only if you have multiple <cfchartseries> tags in your chart; this value becomes the way that the target page knows which series the user clicked.

NOTE

Note the use of $ to delimit variables.

These values will be passed to the target page as URL parameters, which can then be used to display additional data or perform any needed processing.

URL parameters were covered in Chapter 8, "URL Variables."

Plotting Individual Points with <cfchartdata>

The most common way to provide the actual data to a <cfchartseries> tag is to specify a query attribute, then tell ColdFusion which columns of the query to look in by specifying itemcolumn and valuecolumn attributes.

It is also possible to omit the query, itemcolumn, and valuecolumn attributes and instead plot the data points individually using the <cfchartdata> tag, nested within your <cfchartseries>. The <cfchartdata> approach can come in handy if you want to permanently hard-code certain data points onto your charts, if you need to format your data in a special way, or if you come across any other situation in which you can't extract the desired data from a query in a completely straightforward manner.

Table 20.7 shows the syntax for the <cfchartdata> tag.

Table 20.7. <cfchartdata> Syntax

ATTRIBUTE	DESCRIPTION
item	The item associated with the data point you are plotting, such as a film title, a category of purchases, or a period of timein other words, the information you would normally supply to the itemcolumn attribute of the <cfchartseries> tag.
value	The value of the data point (a number). This is what you would normally supply to the valuecolumn attribute of <cfchartseries>.

TIP

It is also possible to mix query driven series and explicit data points if needed.