View comments | RSS feed

cfchart

Description

Generates and displays a chart.

Category

Data output tags, Extensibility tags; Controlling chart appearance in 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 = "hexadecimal value or web color" 
      chartHeight = "integer number of pixels" 
      chartWidth = "integer number of pixels" 
      dataBackgroundColor = "hexadecimal value or web color" 
      font = "font name" 
      fontBold = "yes" or "no" 
      fontItalic = "yes" or "no" 
      fontSize = "font size" 
      foregroundColor = "hexadecimal value or web color" 
      format = "flash" or "jpg" or "png" 
      gridlines = "integer number of lines" 
      labelFormat = "number" or "currency" or "percent" or "date" 
      markerSize = "integer number of pixels" 
      name = "String"
      pieSliceStyle = "solid" or "sliced" 
      scaleFrom = "integer minimum value" 
      scaleTo = "integer maximum value" 
      seriesPlacement = "default" or "cluster" or "stacked" or "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 = "hexadecimal value or web color" 
      tipStyle = "MouseDown" or "MouseOver" or "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 Updater: Changed documentation to state that the fontSize attribute can accept a number that is not an integer.

ColdFusion MX 7:

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 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. 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 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.

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:

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

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>

ColdFusion 9 | ColdFusion 8 | ColdFusion MX 7 | ColdFusion MX 6.1 | ColdFusion MX | Forums | Developer Center | KnowledgeBase | Bug Reporting

Version 7

Comments


prayank said on Apr 12, 2005 at 9:39 PM :
Applying custom styles to cfchart tag

1. Create a custom style by using the webcharts designer. (<cfinstall>\charting\webcharts.bat)
2. The custom style is in the style tab of the webcharts GUI.
3. Save this xml in a file to your web root/ directory where you have the cfm to create the graph. (e.g. you save the file by name "myStyle.xml" in wwwroot\charts directory.
4. Use the "style" attribute to import these settings in the <cfchart> tag. e.g.
you have cfm in wwwroot folder then you can say -
<cfchart style="charts\myStyle.xml" .... other attributes>

regards
Prayank
jrunrandy said on May 18, 2005 at 6:31 AM :
This technote discusses an "image expired" problem with cfchart: http://www.macromedia.com/go/tn_19328
prayank said on Aug 2, 2005 at 12:08 AM :
I suggest cfchart users to check out my blog - <b><a href="http://cfchart.blogspot.com">Looking for help with CFChart?</a></b>

cheers
Prayank
rainbird said on Aug 11, 2005 at 7:16 AM :
The history section of the cfchart tag states the "rotated" attribute has been removed; however the "Attributes" table still includes the rotated attribute. Please update your attributes table.

To show horizontal bars use the cfchartseries type="horizontalbar".
beefo said on Oct 5, 2005 at 6:29 AM :
hey,

two major mistakes in this page:

- pieSliceStyle attributes has default to SOLID and not SLICED as said above
- show3D attributes has default to NO and not YES as said above

;o) happy coding to all !

beefo
ASandstrom said on Nov 15, 2005 at 10:57 AM :
There is a tech note, "ColdFusion MX 7 and MX 7.0.1: Hot fix available for cfchart output not displaying with IIS 6" at http://www.macromedia.com/cfusion/knowledgebase/index.cfm?id=37fc8e9e.
matthewes said on Jan 8, 2006 at 12:33 PM :
Note that the default for seriesplacement is not actually "default" but rather "clustered". You will only notice a difference if you are viewing 3D graphs. This is probably a server bug rather than a docs bug so I'll report it as one.
jagz78 said on Apr 5, 2006 at 3:34 PM :
This page states that the default for showLegend is yes when in fact it is no. I wish it were yes since it was in CF6 now I have to add this value to all my charts that were previously created in CF6 so that the legend will show in CF7.
captaincanard said on Aug 4, 2006 at 6:23 AM :
Concerning the "URL" attribute AFAIK you can't directly target to another window. To do so you must pass $ITEMLABEL$ variable via javascript. But it is problematic when $ITEMLABEL$ contains special characters like apostrophes. Indeed in this particular case JsStringFormat (with or without # signs) does exactly nothing : apostrophe are not escaped and generate a javascript "missing ) after argument list". I believe it is a bug.

<cfchart
style="/charts/templates/mdb_pie.xml"
format="flash"
rl="javascript:Chart_OnClick('JsStringFormat($ITEMLABEL$)');">
<cfchartseries
...>
</cfchartseries>
</cfchart>

<script>
function Chart_OnClick(theItem)
{
theUrl = '/test.cfm?item=' + theItem';
pop_up=window.open(theUrl,'pop_up_frame');
}
</script>
No screen name said on Oct 7, 2006 at 10:46 PM :
I see a lot of postings on other blogs about removing the x-axis labels. In the default.xml file of the CFusionMX7/charting/styles directory, add isVisible="false" in the <xaxis> tag. So it looks like <xaxis isVisible="false">.

This changes the default frameChart style. You can create your own style by copying the xml file and renaming it with a different file name. Be sure to point to this new file with the styles="" command in the cfchart tag.
RyanZircon said on Feb 12, 2007 at 7:59 AM :
Many people run into the problem of having x axis labels like 3.7033333. To get around this, make sure your scaleTo and gridLines values match this formula:

scaleTo must be evenly divisible by (gridLines - 1)

For example:
<cfscript>
gridLines = 12;
scaleTo = your_max_value_to_be_graphed;

while ( scaleTo mod (gridLines - 1) NEQ 0) { scaleTo = scaleTo + 1;}
</cfscript>

 

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/coldfusion/7/htmldocs/00000226.htm