cfchart

Description

Generates and displays a chart.

Syntax

Syntax 1
<!--- This syntax uses an XML file or string to specify the chart style. --->
<cfchart
      style = "XML string or filename"> 
</cfchart>
Syntax 2
<!--- This syntax uses the attributes of the cfchart tag to specify the chart style. --->
<cfchart 
      backgroundColor = "Hex value or Web color" 
      chartHeight = "integer number of pixels" 
      chartWidth = "integer number of pixels" 
      dataBackgroundColor = "Hex value or Web color" 
      font = "font name" 
      fontBold = "yes" or "no" 
      fontItalic = "yes" or "no" 
      fontSize = "integer font size" 
      foregroundColor = "Hex value or Web color" 
      format = "flash" or "jpg" or "png" 
      gridlines = "integer number of lines" 
      labelFormat = "number, currency, percent, date" 
      markerSize = "integer number of pixels" 
      name = "String">
      pieSliceStyle = "solid, sliced" 
      scaleFrom = "integer minimum value" 
      scaleTo = "integer maximum value" 
      seriesPlacement = "default, cluster, stacked, percent" 
      show3D = "yes" or "no" 
      showBorder = "yes" or "no" 
      showLegend = "yes" or "no" 
      showMarkers = "yes" or "no" 
      showXGridlines = "yes" or "no" 
      showYGridlines = "yes" or "no" 
      sortXAxis = "yes" or "no" 
      tipBGColor = "hex value or web color" 
      tipStyle = "MouseDown, MouseOver, none"
      title = "title of chart"
      url = "onClick destination page" 
      xAxisTitle = "title text" 
      xAxisType = "scale or category"
      xOffset = "number between -1 and 1" 
      yAxisTitle = "title text" 
      yAxisType = "scale or category"
      yOffset = "number between -1 and 1" 
      </cfchart>

History

ColdFusion MX 7:

Added style and title attributes.
Added support for eight-digit hexadecimal values to specify RGB color and transparency.
Removed the rotated attribute.
Renamed the column chart type to be horizontalbar chart type.

ColdFusion MX 6.1:

Added the xAxisType and yAxisType attributes.
Changed interpolation behavior: the tag now interpolates data points on line charts with multiple series.

ColdFusion MX: Added this tag.

Attributes

Attribute	Req/Opt	Default	Description
`backgroundColor`	Optional		Color of the area between the data background and the chart border, around labels and around the legend. Hexadecimal value or supported named color; see the name list in Usage. For a hexadecimal value, use the form `"##xxxxxx"` or `"##xxxxxxxx"`, where x = 0-9 or A-F; use two number signs or none.
`chartHeight`	Optional	240	Chart height; integer number of pixels.
`chartWidth`	Optional	320	Chart width; integer number of pixels.
dataBackgroundColor	Optional	white	Color of area around chart data. Hexadecimal value or supported named color; see the name list in Usage. For a hexadecimal value, use the form `"##xxxxxx"` or `"##xxxxxxxx"`, where x = 0-9 or A-F; use two number signs or none.
font	Optional	arial	Name of text font: arial times courier arialunicodeMS. This option is required, if you are using a double-byte character set on UNIX, or using a double-byte character set in Windows with a file type of Flash.
fontBold	Optional	no	Whether to make the text bold: yes no
fontItalic	Optional	no	Whether to make the text italicized: yes no
fontSize	Optional	11	Font size; integer.
foregroundColor	Optional	black	Color of text, grid lines, and labels. Hexadecimal value or supported named color; see name list in Usage. For a hexadecimal value, use the form `"##xxxxxx"` or `"##xxxxxxxx"`, where x = 0-9 or A-F; use two number signs or none.
format	Optional	flash	File format in which to save the graph: flash jpg png
gridlines	Optional	10, including top and bottom	Number of grid lines to display on the value axis, including axis; positive integer.
labelFormat	Optional	number	Format for y-axis labels: number currency percent date
markerSize	Optional	(Automatic)	Size of data point marker in pixels; integer.
name	Optional		Page variable name; string. Generates the the graph as binary data and assigns it to the specified variable. Suppresses chart display. You can use the `name` value in the `cffile` tag to write the chart to a file.
pieSliceStyle	Optional	sliced	Applies to the `cfchartseries` `type` attribute value `pie`. solid: displays pie as if unsliced. sliced: displays pie as if sliced.
rotated	Optional	no	Whether to rotate the chart 90 degrees: yes no
scaleFrom	Optional	Determined by data	Y-axis minimum value; integer.
scaleTo	Optional	Determined by data	Y-axis maximum value; integer.
seriesPlacement	Optional	default	Relative positions of series in charts that have more than one data series. default: ColdFusion determines relative positions, based on graph types cluster stacked percent
show3D	Optional	yes	Whether to display the chart with three-dimensional appearance: yes no
showBorder	Optional	no	Whether to display a border around the chart: yes no
showLegend	Optional	yes	Whether to display the legend if the chart contains more than one data series: yes no
showMarkers	Optional	yes	Whether to display markers at data points in line, curve, and scatter graphs: yes no
showXGridlines	Optional	no	Whether to display x-axis gridlines: yes no
showYGridlines	Optional	yes	Whether to display y-axis gridlines: yes no
sortXAxis	Optional	no	Whether to display column labels in alphabetic order along the x-axis: yes: no Ignored if the `xAxisType` attribute is `scale`.
style	Optional		XML file or string to use to specify the style of the chart.
title	Optional		Title of the chart.
tipbgcolor	Optional	white	Background color of tips. Applies only to Flash format graph files. Hexadecimal value or supported named color; see the name list in the Usage section. For a hexadecimal value, use the form `"##xxxxxx"`, where x = 0-9 or A-F; use two number signs or none.
tipStyle	Optional	mouseOver	Determines the action that opens a pop-up window to display information about the current chart element. mouseDown: display if the user positions the cursor at the element and clicks the mouse. Applies only to Flash format graph files. (For other formats, this option functions the same as `mouseOver`.) mouseOver: displays if the user positions the cursor at the element none: suppresses display
url	Optional		URL to open if the user clicks item in a data series; the `onClick` destination page. You can specify variables within the URL string; ColdFusion passes current values of the variables. $VALUE$ : the value of the selected row. If none, the value is an empty string. $ITEMLABEL$ : the label of the selected item. If none, the value is an empty string. $SERIESLABEL$ : the label of the selected series. If none, the value is an empty string. For example: "somepage.cfm?item=$ITEMLABEL$&series=$SERIESLABEL$&value=$VALUE$ "javascript:...": executes a client-side script
xAxisTitle	Optional		Title that appears on the x-axis; text.
xAxisType	Optional	category	Whether the x-axis indicates data or is numeric: category: The axis indicates the data category. Data is sorted according to the `sortXAxis` attribute. scale: The axis is numeric. All `cfchartdata` `item` attribute values must be numeric. The x-axis is automatically sorted numerically.
xOffset	Optional	0.1	Number of units by which to display the chart as angled, horizontally. Applies if `show3D="yes"`. The number can be between -1 and 1, where "-1" specifies 90 degrees left and "1" specifies 90 degrees right.
yAxisTitle	Optional		Title of the y-axis; text.
yAxisType	Optional	category	Currently has no effect, as the y-axis is always used for data values.
yOffset	Optional	0.1	Number of units by which to display the chart as angled, vertically. Applies if `show3D="yes"`. The number can be between -1 and 1, where "-1" specifies 90 degrees left and "1" specifies 90 degrees right.

Usage

The cfchart tag defines a container in which a graph displays: its height, width, background color, labels, and so on. The cfchartseries tag defines the chart style in which data displays: bar, line, pie, and so on. The cfchartdata tag defines a data point.

Data is passed to the cfchartseries tag in the following ways:

As a query
As data points, using the cfchartdata tag

For the font attribute value ArialUnicodeMS, the following rules apply:

In Windows, to permit Flash charts (type = "flash") to render a double-byte character set, you must select this value.
On UNIX, for all type values, to render a double-byte character set, you must select this value.
If this value is selected, the fontBold and fontItalic attributes have no effect.

The following table lists W3C HTML 4 named color value or hexadecimal values that the color attribute accepts:

Color name	RGB value
Aqua	##00FFFF
Black	#000000
Blue	##0000FF
Fuchsia	##FF00FF
Gray	##808080
Green	##008000
Lime	##00FF00
Maroon	##800000
Navy	##000080
Olive	##808000
Purple	##800080
Red	##FF0000
Silver	##C0C0C0
Teal	##008080
White	##FFFFFF
Yellow	##FFFF00

For all other color values, you must enter the hexadecimal value. You can enter a six-digit value, which specifies the RGB value, or an eight-digit value, which specifies the RGB value and the transparency. The first two digits of an eight-digit hexadecimal value specify the degree of transparency, with FF indicating opaque and 00 indicating transparent. Values between 00 and FF are allowed.

For more color names that are supported by popular browsers, go to www.w3.org/TR/css3-color

You can specify whether charts are cached in memory, the number of charts to cache, and the number of chart requests that ColdFusion can process concurrently. To set these options in the ColdFusion Administrator, select Server Settings > Charting.

Example

<!---The following example analyzes the salary data in the cfdocexamples
database and generates a bar chart showing average salary by department. The
body of the cfchartseries tag includes one cfchartdata tag to include data that
is not available from the query. --->

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

<!--- Use a query of queries to generate a new query with --->
<!--- statistical data for each department. --->
<!--- AVG and SUM calculate statistics. --->
<!--- GROUP BY generates results for each department. --->
<cfquery dbtype = "query" name = "DataTable">
SELECT 
Dept_Name,
AVG(Salary) AS avgSal,
SUM(Salary) AS sumSal
FROM GetSalaries
GROUP BY Dept_Name
</cfquery>

<!--- Reformat the generated numbers to show only thousands. --->
<cfloop index = "i" from = "1" to = "#DataTable.RecordCount#">
<cfset DataTable.sumSal[i] = Round(DataTable.sumSal[i]/1000)*1000>
<cfset DataTable.avgSal[i] = Round(DataTable.avgSal[i]/1000)*1000>
</cfloop>

<h1>Employee Salary Analysis</h1> 
<!--- Bar graph, from Query of Queries --->
<cfchart format="flash" 
xaxistitle="Department" 
yaxistitle="Salary Average"> 

<cfchartseries type="bar" 
query="DataTable" 
itemcolumn="Dept_Name" 
valuecolumn="avgSal">

<cfchartdata item="Facilities" value="35000">

</cfchartseries>
</cfchart>

View comments in LiveDocs