|
cfchart
DescriptionGenerates
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.
HistoryColdFusion
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:
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:
|
fontBold
|
Optional
|
no
|
Whether to make the text bold:
|
fontItalic
|
Optional
|
no
|
Whether to make the text italicized:
|
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:
|
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.
|
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.
|
show3D
|
Optional
|
yes
|
Whether to display the chart with three-dimensional
appearance:
|
showBorder
|
Optional
|
no
|
Whether to display a border around the chart:
|
showLegend
|
Optional
|
yes
|
Whether to display the legend if the chart
contains more than one data series:
|
showMarkers
|
Optional
|
yes
|
Whether to display markers at data points
in line, curve, and scatter graphs:
|
showXGridlines
|
Optional
|
no
|
Whether to display x-axis gridlines:
|
showYGridlines
|
Optional
|
yes
|
Whether to display y-axis gridlines:
|
sortXAxis
|
Optional
|
no
|
Whether to display column labels in alphabetic
order along the x axis:
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.
|
UsageThe 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:
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>
|