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:
- Open the chartdata.cfm file in your editor.
- 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>
Save the file.
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 |
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:
- Open chartdata.cfm in your editor.
- 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>
- 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>
- Save the file.
- 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:
- Open chartdata.cfm your editor.
- 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>
- 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>
- 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>
- Save the page.
- 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".
Comments