Controlling Graph Appearance

The cfgraph tag allows you to customize the appearance of your graph in many ways.

Common graph characteristics

You can optionally specify the following characteristics on all types of graphs:

Graph characteristic

Attributes used

Description

Title
title
titleFont
The title to display on the graph and the font to use.

File Type
fileFormat
Whether to send the graph to the user as a jpeg or Flash (.swf) file. Flash is the default format. On pie and bar charts, Flash supports rollover display of data values and data drill-down by clicking on the data point (using the URLColumn attribute).

Dimensions
graphWidth
graphHeight
The width and height in pixels of the graph. This size defines the entire graph area, including the legend and background area around the graph.
You cannot use these attributes to change the ratio of the data area height to width. For example, you cannot set a large graphWidth value to stretch just the horizontal dimension. To change the overall graph size, specify both the graphHeight and graphWidth.

Background
backgroundColor
The background color to use for the entire graph area, including legends and margins. You can specify any of the standard 256 Web colors. You can use any valid HTML color format. If you use the numeric format, you must use double pound signs, for example, ##CCFFFF.

Border
borderWidth
borderColor
The border that surrounds the graph. You specify the width in pixels and the color using any valid HTML color format, as described for the backgroundColor. A value of 0 means no border.

3D Appearance
depth
The depth of the shading that gives the graph three-dimensional appearance, in pixels. A value of 0 (the default) means no 3D appearance.

Graph characteristic	Attributes used	Description
Title	title titleFont	The title to display on the graph and the font to use.
File Type	fileFormat	Whether to send the graph to the user as a jpeg or Flash (.swf) file. Flash is the default format. On pie and bar charts, Flash supports rollover display of data values and data drill-down by clicking on the data point (using the `URLColumn` attribute).
Dimensions	graphWidth graphHeight	The width and height in pixels of the graph. This size defines the entire graph area, including the legend and background area around the graph. You cannot use these attributes to change the ratio of the data area height to width. For example, you cannot set a large `graphWidth` value to stretch just the horizontal dimension. To change the overall graph size, specify both the `graphHeight` and `graphWidth`.
Background	backgroundColor	The background color to use for the entire graph area, including legends and margins. You can specify any of the standard 256 Web colors. You can use any valid HTML color format. If you use the numeric format, you must use double pound signs, for example, ##CCFFFF.
Border	borderWidth borderColor	The border that surrounds the graph. You specify the width in pixels and the color using any valid HTML color format, as described for the `backgroundColor`. A value of 0 means no border.
3D Appearance	depth	The depth of the shading that gives the graph three-dimensional appearance, in pixels. A value of 0 (the default) means no 3D appearance.

Setting bar and horizontal bar chart characteristics

You can specify the following additional characteristics for bar and horizontal bar charts:

Graph characteristic

Attributes used

Description

Value labels
showValueLabel
valueLabelFont
valueLabelSize
valueLocation
Labels that display the numeric value being graphed.
By default, value labels are on. You can turn them off or have them display when the user points to the bar (Flash file format only). You can specify the font type (Arial, Courier, or Times), point size, and location (OnBar or OverBar).

Value axis
scaleFrom
scaleTo
The minimum and maximum points on the data axis (vertical axis for bar charts, horizontal axis for horizontal bar charts.
By default the minimum is 0 and the maximum is the largest data value.

Grid lines
gridLines
The number of grid lines between the top and bottom of the graph.
The value of each grid line appears along the value axis. The cfgraph tag displays horizontal grids only. A value of 0 (the default) means no grid lines.

Item labels
showItemLabel
itemLabelFont
itemLabelSize
itemLabelOrientation
Labels to show on the second axis of the chart.
Item labels are on by default if you specify an itemColumn (or for cfgraphdata tags, item) attribute. You can specify the label font type (Arial, Courier, or Times), point size, and orientation (horizontal or vertical).

Data point colors
colorList
A comma-separated list of colors to use for each bar.
You can use any of the 256 standard Web colors and any valid Web color name notation (for example, blue or ##FF33CC). You must use double pound signs with hexadecimal color notation. These colors replace the standard system-defined colors. 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.

Bar spacing
barSpacing
The space, in pixels, between bars.
Any 3D shadow specified by the depth attribute appears in this space, so if you want the background to appear between all bars, make the barSpacing value greater than the depth value.

Graph characteristic	Attributes used	Description
Value labels	showValueLabel valueLabelFont valueLabelSize valueLocation	Labels that display the numeric value being graphed. By default, value labels are on. You can turn them off or have them display when the user points to the bar (Flash file format only). You can specify the font type (Arial, Courier, or Times), point size, and location (OnBar or OverBar).
Value axis	scaleFrom scaleTo	The minimum and maximum points on the data axis (vertical axis for bar charts, horizontal axis for horizontal bar charts. By default the minimum is 0 and the maximum is the largest data value.
Grid lines	gridLines	The number of grid lines between the top and bottom of the graph. The value of each grid line appears along the value axis. The `cfgraph` tag displays horizontal grids only. A value of 0 (the default) means no grid lines.
Item labels	showItemLabel itemLabelFont itemLabelSize itemLabelOrientation	Labels to show on the second axis of the chart. Item labels are on by default if you specify an `itemColumn` (or for `cfgraphdata` tags, `item`) attribute. You can specify the label font type (Arial, Courier, or Times), point size, and orientation (horizontal or vertical).
Data point colors	colorList	A comma-separated list of colors to use for each bar. You can use any of the 256 standard Web colors and any valid Web color name notation (for example, blue or ##FF33CC). You must use double pound signs with hexadecimal color notation. These colors replace the standard system-defined colors. 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.
Bar spacing	barSpacing	The space, in pixels, between bars. Any 3D shadow specified by the `depth` attribute appears in this space, so if you want the background to appear between all bars, make the `barSpacing` value greater than the `depth` value.

Example: adding character to a bar graph

The example in the following procedure adds a title to the bar graph and changes its appearance from the default, flat look, to a 3D look. It adds gridlines, sets the maximum Y-axis value to 100000, separates the bars, and uses a custom set of colors.

To enhance the bar graph:

Open graphdata.cfm in ColdFusion Studio.

Edit the cfgraph tag so that it appears as follows:

<!--- Bar graph, from Query of Queries --->

<cfgraph type="bar" 

  query="DeptSalaries" 

  valueColumn="AvgByDept" 

  itemColumn="Dept_Name"

  title = "Average Salary by Department"

  depth = 10

  scaleTo = 100000

  itemLabelSize=16

  itemLabelOrientation="horizontal"

  colorList = "red,orange,green,teal,purple"

  gridLines = 4

  barSpacing = 15>

</cfgraph>

Save the page.
Return to your browser and enter the following URL to view graphdata.cfm:
http://127.0.0.1/myapps/graphdata.cfm

Reviewing the code

The following table describes the highlighted code and its function:

Code

Description

title = "Average Salary by Department"
Put a title above the graph.

depth = 10
Give the graph 10 pixels of 3D "depth" shadow.

scaleTo = 100000
Set the maximum value of the vertical axis to 100000. The minimum value is the default, 0.

itemLabelSize=16
Make the labels on the horizontal axis 16 points.

itemLabelOrientation="horizontal"
Make the labels horizontal on the horizontal axis.

colorList = "red,orange, green,teal,purple"
Get the bar colors from a custom list. In this example, the graph does not use purple because there are only four data points.

gridLines = 4
Display four grid lines between the top and bottom of the graph.

barSpacing = 15
Separate the bars by 15 pixels of background.

Code	Description
title = "Average Salary by Department"	Put a title above the graph.
depth = 10	Give the graph 10 pixels of 3D "depth" shadow.
scaleTo = 100000	Set the maximum value of the vertical axis to 100000. The minimum value is the default, 0.
itemLabelSize=16	Make the labels on the horizontal axis 16 points.
itemLabelOrientation="horizontal"	Make the labels horizontal on the horizontal axis.
colorList = "red,orange, green,teal,purple"	Get the bar colors from a custom list. In this example, the graph does not use purple because there are only four data points.
gridLines = 4	Display four grid lines between the top and bottom of the graph.
barSpacing = 15	Separate the bars by 15 pixels of background.

Setting pie chart characteristics

You can specify the following additional characteristics for pie charts:

Graph characteristic

Attributes used

Description

Value labels
showValueLabel
valueLabelFont
valueLabelSize
valueLocation
Labels that display the numeric value being graphed.
Value labels are on by default. You can turn them off or have them display when the user points to the bar (Flash file format only). You can specify the font type (Arial, Courier, or Times), point size, and location (OnBar or OverBar).

Legend
showLegend
legendFont
A legend relating the pie slice colors to the data point Item descriptions from the itemColumn attribute or cfgraphdata tag itemColumn attribute.
By default the legend appears to the left of the chart. You can also specify above, below, right, and none. You can specify the font type as Arial (the default), Courier, or Times.

Data point colors
colorList
A comma separated list of colors to use for each bar.
You can use any of the 256 standard Web colors and any valid Web color name notation (for example, blue or ##FF33CC). You must use double pound signs with hexadecimal color notation. These colors replace the standard system-defined colors.
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.

Graph characteristic	Attributes used	Description
Value labels	showValueLabel valueLabelFont valueLabelSize valueLocation	Labels that display the numeric value being graphed. Value labels are on by default. You can turn them off or have them display when the user points to the bar (Flash file format only). You can specify the font type (Arial, Courier, or Times), point size, and location (OnBar or OverBar).
Legend	showLegend legendFont	A legend relating the pie slice colors to the data point Item descriptions from the `itemColumn` attribute or `cfgraphdata` tag `itemColumn` attribute. By default the legend appears to the left of the chart. You can also specify above, below, right, and none. You can specify the font type as Arial (the default), Courier, or Times.
Data point colors	colorList	A comma separated list of colors to use for each bar. You can use any of the 256 standard Web colors and any valid Web color name notation (for example, blue or ##FF33CC). You must use double pound signs with hexadecimal color notation. These colors replace the standard system-defined colors. 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.

Example: adding a pie chart

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

To create a pie chart:

Open graphdata.cfm in ColdFusion Studio.

Edit the DeptSalaries query and the cfloop code so that they appear 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 cfgraph tag before the end of the body:

<!--- Pie graph, from DeptSalaries Query of Queries --->

<cfgraph type="pie" 

  query="DeptSalaries" 

  valueColumn="SumByDept" 

  itemColumn="Dept_Name" 

  title="Total Salaries by Department" 

  titleFont="Times"

  showValueLabel="rollover" 

  valueLabelFont="Times"

  borderWidth = 0

  backgroundColor = "##CCFFFF"

  colorlist="##6666FF,##66FF66,##FF6666,##66CCCC"

  LegendFont="Times">

</cfgraph>

<br>

Save the page.
Return to your browser and enter the following URL to view graphdata.cfm:
http://127.0.0.1/myapps/graphdata.cfm

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, round the salary sums to the nearest thousand.

<cfgraph type="pie" query="DeptSalaries" valueColumn="SumByDept"
Create a pie graph using the SumByDept salary sum values from the DeptSalares query.

itemColumn="Dept_Name"
Use the contents of the Dept_Name column for the item labels displayed in the chart legend.

title="Total Salaries by Department" titleFont="Times"
Put a title above the graph.
Format it in Times font.

showvalue="rollover" valueLabelFont="Times"
Display the data value, in Times font, only when the user points to a pie slice.

borderWidth = 0
Do not put a border around the chart

backgroundColor = "##CCFFFF" colorList = "##6666FF,##66FF66, ##FF6666,##66AAAA"
Set the background for the entire chart area to a light blue.
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.

LegendFont="Times"
Use Times font for the legend.

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`, round the salary sums to the nearest thousand.
<cfgraph type="pie" query="DeptSalaries" valueColumn="SumByDept"	Create a pie graph using the SumByDept salary sum values from the DeptSalares query.
itemColumn="Dept_Name"	Use the contents of the Dept_Name column for the item labels displayed in the chart legend.
title="Total Salaries by Department" titleFont="Times"	Put a title above the graph. Format it in Times font.
showvalue="rollover" valueLabelFont="Times"	Display the data value, in Times font, only when the user points to a pie slice.
borderWidth = 0	Do not put a border around the chart
backgroundColor = "##CCFFFF" colorList = "##6666FF,##66FF66, ##FF6666,##66AAAA"	Set the background for the entire chart area to a light blue. 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.
LegendFont="Times"	Use Times font for the legend.

Setting line and area graph characteristics

You can specify the following additional characteristics for line-based graphs

Graph characteristic

Attributes used

Description

Value axis
scaleFrom
scaleTo
The minimum and maximum points on the vertical axis.
By default the minimum is 0 and the maximum is the largest data value.

Item labels
showItemLabel
itemLabelFont
itemLabelSize
itemLabelOrientation
Labels to show on the horizontal axis of the chart.
By default, item labels are on if you specify an itemColumn (or for cfgraphdata tags, item) attribute. You can specify the label font type (Arial, Courier, or Times), point size, and orientation (horizontal or vertical).

Line characteristics
lineColor
lineWidth
These attributes specify the line format.
For the line color, you can use any of the 256 standard Web colors and any valid Web color name notation (for example, blue or ##FF33CC). You must use double pound signs with hexadecimal color notation. The default line color is blue.
You can also specify the line width in pixels. The default is 1 pixel.

Area fill
fill
Specifies whether to fill the area below the line with the line color to form an area graph By default there is no fill.

Grid lines
gridLines
The number of grid lines between the top and bottom of the graph. The value of each grid line appears along the value axis. The cfgraph tag displays horizontal grids only. A value of 0 (the default) means no grid lines.

Graph characteristic	Attributes used	Description
Value axis	scaleFrom scaleTo	The minimum and maximum points on the vertical axis. By default the minimum is 0 and the maximum is the largest data value.
Item labels	showItemLabel itemLabelFont itemLabelSize itemLabelOrientation	Labels to show on the horizontal axis of the chart. By default, item labels are on if you specify an `itemColumn` (or for `cfgraphdata` tags, `item`) attribute. You can specify the label font type (Arial, Courier, or Times), point size, and orientation (horizontal or vertical).
Line characteristics	lineColor lineWidth	These attributes specify the line format. For the line color, you can use any of the 256 standard Web colors and any valid Web color name notation (for example, blue or ##FF33CC). You must use double pound signs with hexadecimal color notation. The default line color is blue. You can also specify the line width in pixels. The default is 1 pixel.
Area fill	fill	Specifies whether to fill the area below the line with the line color to form an area graph By default there is no fill.
Grid lines	gridLines	The number of grid lines between the top and bottom of the graph. The value of each grid line appears along the value axis. The `cfgraph` tag displays horizontal grids only. A value of 0 (the default) means no grid lines.

Example: adding an area graph

The example in the following procedure adds an area graph 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; in this example, the average salary by start date. It also shows the use of additional cfgraph attributes.

To create an area graph:

Open graphdata.cfm in ColdFusion Studio.

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 cfgraph tag before the end of the body tag block.

<!--- Area-style Line graph, from HireSalaries Query of Queries --->

<cfgraph type="line" 

  query="HireSalaries" 

  valueColumn="AvgByStart" 

  itemColumn="StartDate"

  title="Average Salaries by Date of Hire" 

  fileFormat="Flash"

  GraphWidth=400

  BackgroundColor="##FFFF00"

  Depth=5

  lineColor="teal"

  fill="yes" >

</cfgraph>

<br>

Save the page.
Return to your browser and enter the following URL to view graphdata.cfm:
http://127.0.0.1/myapps/graphdata.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 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.

<cfgraph type="line" query="HireSalaries" valueColumn="AvgByStart" itemColumn="StartDate"
Create a line graph using the HireSalaries query. Graph the average salaries against the start date.

title="Average Salaries by Date of Hire"
Title the graph.

fileFormat="Flash"
Send the graph to the user as a Flash file.

GraphWidth=400
Limit the graph width to 400 pixels. Generator automatically resizes the graph's height to maintain the aspect ratio.

BackgroundColor="##FFFF00" Depth=5 lineColor="teal"
Display a 3D graph in teal against a yellow background.

fill="yes"
Fill the region below the graph to create an area graph.

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` 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.
<cfgraph type="line" query="HireSalaries" valueColumn="AvgByStart" itemColumn="StartDate"	Create a line graph using the HireSalaries query. Graph the average salaries against the start date.
title="Average Salaries by Date of Hire"	Title the graph.
fileFormat="Flash"	Send the graph to the user as a Flash file.
GraphWidth=400	Limit the graph width to 400 pixels. Generator automatically resizes the graph's height to maintain the aspect ratio.
BackgroundColor="##FFFF00" Depth=5 lineColor="teal"	Display a 3D graph in teal against a yellow background.
fill="yes"	Fill the region below the graph to create an area graph.

Developing ColdFusion Applications
Graphing Data