Developing ColdFusion MX Applications with CFML
Charting and Graphing Data

Controlling chart appearance

Use the cfchart and cfchartseries tags to customize the appearance of your charts.

Common chart characteristics

You can optionally specify the following characteristics to cfchart on all types of charts:

Chart characteristic	Attributes used	Description
File type	format	Whether to send the chart to the user as a JPG, PNG, or Flash Movie (.swf) file. Flash is the default format.
Dimensions	chartWidth chartHeight	The width and height, in pixels, of the chart. This size defines the entire chart area, including the legend and background area around the chart. The default height is 240 pixels; the default width is 320 pixels.
Column labels	sortXAxis	Specifies to display the column labels along the x-axis in alphabetical order. The default is no.
Foreground and background color	foregroundColor dataBackgroundColor backgroundColor	The colors used for foreground and background objects. The default foreground color is black; the default background colors are white. You can specify 16 color names or use any valid HTML color format. If you use the numeric format, you must use double pound signs, for example, blue or ##FF33CC. For the complete list of colors, see Administering ColdFusion MX.
Border	showBorder	Specifies to draw a border around the chart. The border color is the same as specified by the foregroundColor attribute. Default is no.
Labels	font fontSize fontBold frontItalic labelFormat xAxisTitle yAxisTitle	font specifies the font for all text. Default is Arial. If you are using a double-byte character set on UNIX, or using a double-byte character set on Windows with a file type of Flash, you must specify ArialUnicodeMs as the font. fontSize speciofies an Integer font size used for all text. Default is 11. fontBold specifies to display all text as bold. Default is no. fontItalic specifies to display all text as italic. Default is no. labelFormat specifies the format of the y-axis labels, number, currency, percent, or date. Default is number. xAxisTitle and yAxisTitle specify the title for each axis.
3-D Appearance	show3D xOffset yOffset	show3D displays the chart in 3-D. Default is no. xOffset and yOffset specify the amount to which the chart should be rotated on a horizontal axis (xOffset) or vertical axis (yOffset). 0 is flat (no rotation), -1 and 1 are for a full 90 degree rotation left (-1) or right (1). Default is .1
Rotation	rotated	Rotates the entire chart 90 degrees. Set to yes to create a horizontal chart, such as a horizontal bar chart. Default is no.
Multiple series	showLegend seriesPlacement	showLegend specifies to display the chart's legend when the chart contains more than one series of data. Default is yes. seriesPlacement specifies the location of each series relative to the others. By default, ColdFusion determines the best placement based on the graph type of each series.
Tips	tipStyle tipBGColor	tipStyle specifies to display a small popup window that shows information about the chart element pointed to by the curser. Options are none, mousedown, or mouseover. Default is mouseover. tipBGColor specifies the background color of the tip window for Flash format only. Default is white.
Markers	showMarkers markerSize	showMarkers specifies to show markers at the data points for 2-D line, curve, and scatter charts. Default is yes. markerSize specifies an integer number of pixels for the marker size. ColdFusion determines default.

You can also use the cfchartseries tag to specify attributes of chart appearance. The following table describes these attributes:

Chart characteristic	Attributes used	Description
Multiple series	seriesLabel seriesColor	seriesLabel specifies the text displayed for the series label. seriesColor specifies a single color of the bar, line, pyramid, and so on. For pie charts, this is the first slice's color. Subsequent slices are automatically colored based on the specified initial color, or use the colorList attribute.
Paint	paintStyle	Specifies the way color is applied to a data series. You can specify solid color, buttonized look, linear gradient fill with a light center and darker outer edge, and gradient fill on lighter version of color. Default is solid.
Data markers	markerStyle	For line, curve, and scatter charts, specifies the shape used to mark the data point. Supported for 2-dimensional charts. Default is rectangle.

Setting x-axis and y-axis characteristics

You can specify the following additional characteristics to control the look of the x-axis and y-axis of charts, except for pie charts:

Chart characteristic	Attributes used	Description
Value axis	scaleFrom scaleTo	The minimum and maximum points on the data axis. By default the minimum is 0 or the lowest negative chart data value, and the maximum is the largest data value.
Grid lines	showXGridlines showYGridlines gridLines	showXGridlines and showYGridlines specify to display x-axis and y-axis grid lines. Default no for x-axis gridlines, and yes for y-axis gridlines. gridLines specifies the total number of grid lines on the value axis, including the axis itself. The value of each grid line appears along the value axis. The cfchart tag displays horizontal grid lines only. A value of 0 (the default) means no grid lines.

Creating a bar chart

The example in the following procedure adds a title to the bar chart and changes its appearance from the default, flat look, to a 3-D look. It adds grid lines, sets the maximum y-axis value to 100,000, and uses a custom set of colors.

To enhance the bar chart:

1. Open the chartdata.cfm file in your editor.
2. Edit the cfchart tag so that it appears as follows:

   <!--- Bar chart, from Query of Queries --->
   <cfchart 
   

    scaleTo = 100000
    fontSize=16
    gridLines = 4 
    show3D="yes"
  >

  <cfchartseries 
    type="bar" 
    query="DeptSalaries" 
    valueColumn="AvgByDept" 
    itemColumn="Dept_Name"
    />

</cfchart>

Reviewing the code

The following table describes the highlighted code and its function:

Code	Description
scaleTo = 100000	Set the maximum value of the vertical axis to 100000. The minimum value is the default, 0.
fontSize=16	Make the point size of the labels 16 points.
gridLines = 4	Display four grid lines between the top and bottom of the chart.
show3D = "yes"	Show the chart in 3-D.

Setting pie chart characteristics

You can specify the following additional characteristics for pie charts:

Chart characteristic	Attributes used	Description
Slice style (cfchart tag)	pieSliceStyle	Display pie chart as solid or sliced. Default is sliced.
Data point colors (cfchartseries tag)	colorList	A comma-separated list of colors to use for each pie slice. You can specify 16 color names or use any valid HTML color format. If you use the numeric format, you must use double pound signs, for example, blue or ##FF33CC. For the complete list of colors, see Administering ColdFusion MX. If you specify fewer colors than data points, the colors repeat. If you specify more colors than data points, the extra colors are not used.

The example in the following procedure adds a pie chart to the page.

To create a pie chart:

1. Open chartdata.cfm in your editor.
2. Edit the DeptSalaries query and the cfloop code so that it appears as follows:

   <!--- A query to get statistical data for each department. --->
   <cfquery dbtype = "query" name = "DeptSalaries">
     SELECT 
       Dept_Name,
       SUM(Salary) AS SumByDept,
       AVG(Salary) AS AvgByDept
     FROM GetSalaries
     GROUP BY Dept_Name
   </cfquery>
   
   <!--- Reformat the generated numbers to show only thousands --->
   <cfloop index="i" from="1" to="#DeptSalaries.RecordCount#">
     <cfset DeptSalaries.SumByDept[i]=Round(DeptSalaries.SumByDept[i]/
   1000)*1000>
     <cfset DeptSalaries.AvgByDept[i]=Round(DeptSalaries.AvgByDept[i]/
   1000)*1000>
   </cfloop>
   

3. Add the following cfchart tag:

   <!--- Pie chart, from DeptSalaries Query of Queries --->
   <cfchart 
       tipStyle="mousedown" 
       font="Times"
       fontsize=14
       fontBold="yes"
       backgroundColor = "##CCFFFF"
       show3D="yes"
       >
       
     <cfchartseries 
       type="pie" 
       query="DeptSalaries" 
       valueColumn="SumByDept" 
       itemColumn="Dept_Name" 
       colorlist="##6666FF,##66FF66,##FF6666,##66CCCC"
       />
   </cfchart>
   <br>
   

4. Save the file.
5. Return to your browser and enter the following URL to view chartdata.cfm:

   http://127.0.0.1/myapps/chartdata.cfm

   The following figure appears:

   

Reviewing the code

The following table describes the highlighted code and its function:

Code	Description
SUM(Salary) AS SumByDept,	In the DeptSalaries query, add a SUM aggregation function to get the sum of all salaries per department.
<cfset DeptSalaries.SumByDept[i]= Round(DeptSalaries.SumByDept[i]/ 1000)*1000>	In the cfloop tag, round the salary sums to the nearest thousand.
<cfchart tipStyle="mousedown" font="Times" fontBold="yes" backgroundColor = "##CCFFFF" show3D="yes" >	Show a tip only when a user clicks on the chart, display text in Times Bold font, set the background color to light blue, and display the chart in 3-D.
<cfchartseries type="pie" query="DeptSalaries" valueColumn="SumByDept" itemColumn="Dept_Name" colorlist= "##6666FF,##66FF66,##FF6666,##66CCCC" />	Create a pie chart using the SumByDept salary sum values from the DeptSalares query. Use the contents of the Dept_Name column for the item labels displayed in the chart legend. Get the pie slice colors from a custom list, which uses hexadecimal color numbers. The double pound signs prevent ColdFusion from trying to interpret the color data as variable names.

Creating an area chart

The example in the following procedure adds an area chart showing the average salary by start date to the salaries analysis page. It shows the use of a second query of queries to generate a new analysis of the raw data from the GetSalaries query. It also shows the use of additional cfchart attributes.

To create an area chart:

1. Open chartdata.cfm your editor.
2. Edit the GetSalaries query so that it appears as follows:

   <!-- Get the raw data from the database. -->
   <cfquery name="GetSalaries" datasource="CompanyInfo">
     SELECT Departmt.Dept_Name, 
       Employee.StartDate,
       Employee.Salary
     FROM Departmt, Employee
     WHERE Departmt.Dept_ID = Employee.Dept_ID
   </cfquery>
   

3. Add the following code before the html tag:

   <!--- Convert start date to start year. --->
   <!--- You must explicitly convert the date to a number for the query to work --->
   <cfloop index="i" from="1" to="#GetSalaries.RecordCount#">
   <cfset GetSalaries.StartDate[i]=NumberFormat(DatePart("yyyy", GetSalaries.StartDate[i]) ,9999)>
   </cfloop>
   
   <!--- Query of Queries for average salary by start year --->
   <cfquery dbtype = "query" name = "HireSalaries">
     SELECT 
       StartDate,
       AVG(Salary) AS AvgByStart
     FROM GetSalaries
     GROUP BY StartDate
   </cfquery>
   
   <!--- Round average salaries to thousands ---> 
   <cfloop index="i" from="1" to="#HireSalaries.RecordCount#">
     <cfset HireSalaries.AvgByStart[i]=Round(HireSalaries.AvgByStart[i]/1000)*1000>
   </cfloop>
   

4. Add the following cfchart tag before the end of the body tag block:

   <!--- Area-style Line chart, from HireSalaries Query of Queries --->
   <cfchart 
       chartWidth=400
       BackgroundColor="##FFFF00"
       show3D="yes"
     >
     <cfchartseries
       type="area" 
       query="HireSalaries" 
       valueColumn="AvgByStart" 
       itemColumn="StartDate"
      />
   </cfchart>
   <br>
   

5. Save the page.
6. Return to your browser and enter the following URL to view chartdata.cfm:

   http://127.0.0.1/myapps/chartdata.cfm

Reviewing the code

The following table describes the highlighted code and its function:

Code	Description
Employee.StartDate,	Add the employee start date to the data in the GetSalaries query.
<cfloop index="i" from="1"     to="#GetSalaries.RecordCount#">   <cfset GetSalaries.StartDate[i]=   NumberFormat(DatePart("yyyy",   GetSalaries.StartDate[i]) ,9999)> </cfloop>	Use a cfloop tag to extract the year of hire from each employee's hire data, and convert the result to a four-digit number.
<cfquery dbtype = "query" name = "HireSalaries">   SELECT      StartDate,     AVG(Salary) AS AvgByStart   FROM GetSalaries   GROUP BY StartDate </cfquery>	Create a second query from the GetSalaries query. This query contains the average salary for each start year.
<cfloop index="i" from="1"    to="#HireSalaries.RecordCount#">   <cfset HireSalaries.AvgByStart[i]   =Round(HireSalaries.AvgByStart[i]   /1000)*1000> </cfloop>	Round the salaries to the nearest thousand.
<cfchart chartWidth=400 BackgroundColor="##FFFF00" show3D="yes" > <cfchartseries type="area" query="HireSalaries" valueColumn="AvgByStart" itemColumn="StartDate" /> </cfchart>	Create a line chart using the HireSalaries query. Chart the average salaries against the start date. Limit the chart width to 400 pixels, show the chart in 3-D, and set the background color to white.

Setting curve chart characteristics

Curves use the attributes already discussed. However, you should be aware that curve charts require a large amount of processing to render. For fastest performance, create them offline, write them to a file or variable, then reference them in your application pages. For information on creating offline charts, see "Writing a chart to a variable".

Copyright © 2002, Macromedia Inc. All rights reserved.

Comments