Building Basic Charts

Now that you have an idea of what you can do with ColdFusion's charting features, it's time to get started with some basic examples. Most of the time, you will create charts with just two CFML tags, <cfchart> and <cfchartseries>.

Introducing <cfchart> and <cfchartseries>

To display a chart on a ColdFusion page, you use the <cfchart> tag. The <cfchart> tag is what controls the height, width, and formatting of your chart, but it doesn't actually display anything. Within the <cfchart> tag, you use the <cfchartseries> tag, which determines the type of chart (like bar or pie) and the actual data to show on the chart.

NOTE

Actually, you will occasionally want to place multiple <cfchartseries> tags within a <cfchart> tag. See the "Combining Multiple Chart Series" section, later in this chapter.

Table 20.1 shows the most important attributes for the <cfchart> tag, and Table 20.2 shows the most important attributes for <cfchartseries>.

Table 20.1. Basic <cfchart> Tag Syntax

ATTRIBUTE	DESCRIPTION
chartwidth	Optional. The width of the chart, in pixels. The default is 320.
chartheight	Optional. The height of the chart, in pixels. The default is 240.
xaxistitle	Optional. The text to display along the chart's x-axis.
yaxistitle	Optional. The text to display along the chart's y-axis.
rotated	Yes or No. If yes, the chart is rotated clockwise by 90 degrees. You can use this to create bar charts that point sideways rather than up and down, and so on. The default is No.
url	Optional. The URL of a page to send the user to when various sections of the chart are clicked. You can pass variables in the URL so you know what part of the chart the user clicked. See "Drilling Down from Charts," later in this chapter.
format	Optional. The type of image format in which the chart should be created. The valid choices are flash (the default), jpg, or png.
seriesplacement	Optional. For charts that have more than one data series, you can use this attributecluster, stacked, percent, or defaultto control how the series are combined visually. Use cluster if the data series represent related pieces of information that should be presented next to one another, rather than added together visually. Use stacked or percent if the data series represent values that should be added up to a single whole value for each item you are plotting. See "Combining Multiple Chart Series," later in this chapter.

Table 20.2. Basic <cfchartseries> Syntax

ATTRIBUTE	DESCRIPTION
type	Required. The type of chart to create. One of area, bar, cone, curve, cylinder, horizontalbar, line, pie, pyramid, scatter, step.
query	Optional. The name of a query that contains data to chart. If you don't provide a query attribute, you will need to provide <cfchartdata> tags to tell ColdFusion the data to display in the chart.
valuecolumn	Required if a query is provided. The name of the column that contains the actual value (the number to represent graphically) for each data point on the chart.
itemcolumn	Required if a query is provided. The name of the column that contains labels for each data point on the chart.

NOTE

Because these tags have a large number of attributes (more than 40 in all), we are introducing only the most important attributes in this table. Others are introduced later in this chapter.

NOTE

In this chapter, you will see the term data point often. Data points are the actual pieces of data that are displayed on a chart. If you are creating a pie chart, the data points are the slices of the pie. In a bar chart, the data points are the bars. In a line or scatter chart, the data points are the individual points that have been plotted on the graph.

NOTE

You don't have to have a query object to create a chart. You can also create data points manually using the <cfchartdata> tag. See "Plotting Individual Points with <cfchartdata>," near the end of this chapter.

Creating A Chart

The following example creates a simple bar chart using <cfchart> and <cfchartseries> to create a simple bar chart.

 <!--- Get information from the database ---> <cfquery datasource="myDsn"          name="chartQuery"> SELECT movietitle, amountbudgeted FROM movies WHERE active=1 ORDER BY movietitle </cfquery> <h2>Chart: Film Budgets</h2> <!--- This defines the size and appearance of the chart ---> <cfchart chartwidth="750"          chartheight="500"          yaxistitle="Budget">  <!--- within the chart --->   <cfchartseries type="bar"                  query="chartquery"                 valuecolumn="amountbudgeted"                 itemcolumn="movietitle"> </cfchart> 

The <cfchart> tag is used to establish the size of the chart, and to specify that the word Budget appear along the y-axis (that is, at the bottom of the chart). Within the <cfchart> block, a <cfchartseries> tag is used to create a bar chart. ColdFusion is instructed to chart the information in the ChartQuery record set, plotting the data in the AmountBudgeted column and using the MovieTitle column to provide a label for each piece of information.

The above code will create a Flash chart, as that is the default chart format generated by ColdFusion. Charts may also be generated as static images (in JPG and PNG formats), although static charts are not as functional or feature rich.

Changing the Chart Type

The previous example created a bar chart. To create a different chart (perhaps a pie chart, simply change the type to one of the values listed in Table 20.2.