cfchart

Description

Generates and displays a chart.

Syntax

<!--- This syntax uses an XML file or string to specify the chart style. ---> 
<cfchart 
    style = "XML string|XML filename">  
</cfchart> 
 
OR 
 
<!--- This syntax uses the attributes of the cfchart tag to specify the chart style. ---> 
<cfchart  
    backgroundColor = "hexadecimal value|web color"  
    chartHeight = "integer number of pixels"  
    chartWidth = "integer number of pixels"  
    dataBackgroundColor = "hexadecimal value|web color"  
    font = "font name"  
    fontBold = "yes|no"  
    fontItalic = "yes|no"  
    fontSize = "font size"  
    foregroundColor = "hexadecimal value|web color"  
    format = "flash|jpg|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|no"  
    showBorder = "yes|no"  
    showLegend = "yes|no"  
    showMarkers = "yes|no"  
    showXGridlines = "yes|no"  
    showYGridlines = "yes|no"  
    sortXAxis = "yes|no"  
    tipBGColor = "hexadecimal value|web color"  
    tipStyle = "MouseDown|MouseOver|none" 
    title = "title of chart" 
    url = "onClick destination page"  
    xAxisTitle = "title text"  
    xAxisType = "scale|category" 
    xOffset = "number between -1 and 1"  
    yAxisTitle = "title text"  
    yAxisType = "scale|category" 
    yOffset = "number between -1 and 1"> 
</cfchart>
Note: You can specify this tag’s attributes in an attributeCollection attribute whose value is a structure. Specify the structure name in the attributeCollection attribute and use the tag’s attribute names as structure keys.

See also

cfchartdata, cfchartseries, cfdocument, Controlling chart appearance in the Developing ColdFusion Applications

History

ColdFusion 8:

  • Added the new attribute showLegend to the chart style files, which are the XML files located in the charting\styles directory- This attribute displays an entry for each point and is applicable only to charts that contain a single series. By default, the value of showLegend is set to true. To turn off this feature, you can either modify the setting in all the chart style files, or use a custom style file.

ColdFusion MX 7.01: Changed documentation to state that the fontSize attribute can accept a number that is not an integer.

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.

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 the Usage section.

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. If the number is not an integer, ColdFusion rounds the number up to the next integer.

foregroundColor

Optional

black

Color of text, grid lines, and labels.

Hexadecimal value or supported named color; see name list in the Usage section.

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 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 cfchartseriestype attribute value pie.

  • solid: displays pie as if unsliced.

  • sliced: displays pie as if sliced.

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 cfchartdataitem 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, select this value.

  • In UNIX, for all type values, to render a double-byte character set, 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, 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>