CFCHART  
Description

Generates and displays a chart.

 
Category

Data output tags, Extensibility tags; "Controlling chart appearance" in Chapter 31, "Creating Charts and Graphs," in ColdFusion MX Developer's Guide

 
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>
 
See also

cfchartdata, cfchartseries

 
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.

 
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:

   

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>
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
 
Default value: "240"

Chart height; integer number of pixels.
CHARTWIDTH  
  Optional
 
Default value: "320"

Chart width; integer number of pixels.
DATABACKGROUNDCOLOR  
  Optional
 
Default value: "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
 
Default value: "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
 
Default value: "no"

Whether to make the text bold:

  • yes
  • no
FONTITALIC  
  Optional 
 
Default value: "no"

Whether to make the text italicized:

  • yes
  • no
FONTSIZE  
  Optional
 
Default value: "11"

Font size; integer.
FOREGROUNDCOLOR  
  Optional
 
Default value: "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
 
Default value: "flash"

File format in which to save the graph:

  • flash
  • jpg
  • png
GRIDLINES  
  Optional
 
Default value: "10, including top and bottom"

Number of grid lines to display on the value axis, including axis; positive integer.
LABELFORMAT  
  Optional
 
Default value: "number"

Format for y-axis labels:

  • number
  • currency
  • percent
  • date
MARKERSIZE  
  Optional 
 
Default value: "(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
 
Default value: "sliced"

Applies to the cfchartseries type attribute value pie.

  • solid: displays pie as if unsliced.
  • sliced: displays pie as if sliced.
ROTATED  
  Optional
 
Default value: "no"

Whether to rotate the chart 90 degrees:

  • yes
  • no
SCALEFROM  
  Optional
 
Default value: "Determined by data"

Y-axis minimum value; integer.
SCALETO  
  Optional
 
Default value: "Determined by data"

Y-axis maximum value; integer.
SERIESPLACEMENT  
  Optional
 
Default value: "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
 
Default value: "yes"

Whether to display the chart with three-dimensional appearance:

  • yes
  • no
SHOWBORDER  
  Optional
 
Default value: "no"

Whether to display a border around the chart:

  • yes
  • no
SHOWLEGEND  
  Optional
 
Default value: "yes"

Whether to display the legend if the chart contains more than one data series:

  • yes
  • no
SHOWMARKERS  
  Optional
 
Default value: "yes "

Whether to display markers at data points in line, curve, and scatter graphs:

  • yes
  • no
SHOWXGRIDLINES  
  Optional
 
Default value: "no"

Whether to display x-axis gridlines:

  • yes
  • no
SHOWYGRIDLINES  
  Optional
 
Default value: "yes"

Whether to display y-axis gridlines:

  • yes
  • no
SORTXAXIS  
  Optional
 
Default value: "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
 
Default value: "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
 
Default value: "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
 
Default value: "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
 
Default value: "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
 
Default value: "category"

Currently has no effect, as the y-axis is always used for data values.

YOFFSET  
  Optional
 
Default value: "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.