Controlling chart appearance



You can control the appearance of charts by doing any of the following:

  • Using the default chart styles included with ColdFusion

  • Using the attributes of the cfchart and cfchartseries tags

  • Creating your own chart styles

Using the default chart styles included with ColdFusion

ColdFusion supplies the following chart styles:

  • beige

  • blue

  • default

  • red

  • silver

  • yellow

To use any of these styles, specify the style using the style attribute of the cfchart tag. The following example illustrates using the beige style:

<cfchart style="beige"> 
    <cfchartseries type="pie"> 
        <cfchartdata item="New car sales" value="50000"> 
        <cfchartdata item="Used car sales" value="25000"> 
        <cfchartdata item="Leasing" value="30000"> 
        <cfchartdata item="Service" value="40000"> 
    </cfchartseries> 
</cfchart>

You can specify the appearance of charts by using the attributes of the cfchart and cfchartseries tags.

You can optionally specify the following characteristics to the cfchart tag on the types of charts indicated:

Chart characteristic

Attributes used

Description

Chart type

File type

format

Whether to send the chart to the user as a JPEG, PNG, or SWF file. The SWF file is the default format.

All

Size

chartWidth

chartHeight

The width and height, in pixels, of the chart. This size defines the entire chart area, including the legend and background area around the chart.

The default height is 240 pixels; the default width is 320 pixels.

All

Color

foregroundColor

dataBackgroundColor

backgroundColor

The colors used for foreground and background objects.

The default foreground color is black; the default background colors are white.

You can specify 16 color names, use any valid HTML color format, or specify an 8-digit hexadecimal value to specify the RGB value and transparency. If you use numeric format, use double number signs; for example, blue or ##FF33CC. To specify the color and transparency, use the format ##xxFF33CC, where xx indicates the transparency. The value FF indicates opaque; the value 00 indicates transparent. For the complete list of colors, see Configuring and Administering ColdFusion.

All

Labels

font

fontSize

fontBold

frontItalic

labelFormat

xAxisTitle

yAxisTitle

The font attribute specifies the font for all text. The default value is Arial. 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, specify ArialUnicodeMs as the font.

Note: If a chart attempts to use a font that is not installed on the ColdFusion server, it uses a different font that is available. Also, if you do not specify the font, characters that are not ASCII, such as Japanese, Chinese, Korean, and so on, can display improperly.

The fontSize specifies an Integer font size used for all text. The default value is 11.

The fontBold attribute specifies to display all text as bold. The default value is no.

The fontItalic attribute specifies to display all text as italic. The default value is no.

The labelFormat attribute specifies the format of the y-axis labels, number, currency, percent, or date. The default value is number.

The xAxisTitle and yAxisTitle attributes specify the title for each axis.

All

Border

showBorder

Use the showBorder attribute to draw a border around the chart. The foregroundColor attribute specifies the border color. The default value is no.

All

Grid lines

showXGridlines

showYGridlines

gridLines

Use the showXGridlines and showYGridlines attributes to display x-axis and y-axis grid lines. The default value no for x-axis gridlines, and yes for y-axis gridlines.

The gridLines attribute specifies the total number of grid lines on the value axis, including the axis itself. The value of each grid line appears along the value axis. The cfchart tag displays horizontal grid lines only. The default value is 0, which means no grid lines.

Area

Bar

Cone

Curve

Cylinder

Horizontalbar

Line

Pyramid

Scatter

Step

Slice style

pieSliceStyle

Displays the pie chart as solid or sliced. The default value is sliced.

Pie

Markers

showMarkers

markerSize

The showMarkers attribute displays markers at the data points for two-dimensional line, curve, and scatter charts. The default value is yes.

The markerSize attribute specifies an integer number of pixels for the marker size. ColdFusion determines the default value.

All

Value axis

scaleFrom

scaleTo

The minimum and maximum points on the data axis.

By default, the minimum is 0 or the lowest negative chart data value, and the maximum is the largest data value.

Note: If you specify a scaleFrom or scaleTo attribute that would result in cropping the chart, cfchart uses a value that shows the entire chart without cropping.

Area

Bar

Cone

Curve

Cylinder

Horizontalbar

Line

Pyramid

Scatter

Step

Axis type

XAxisType

sortXAxis

Whether the x axis corresponds to a numeric scale or identifies different categories, and how to sort the items on the axis.

If the XAxisType attribute value is scale, the x axis is numeric. All cfchartdataitem attribute values must be numeric, and the axis is automatically sorted numerically. The scale value lets you create graphs of numeric relationships, such as population against age.

If the attribute value is category (the default), the axis indicates the data category.

The sortXAxis attribute determines the order of items when you specify the cfchartdataitem attribute, whose values are treated as text. By default, the items are displayed in the order in which they are entered in the first chart series.

Area

Bar

Cone

Curve

Cylinder

Horizontalbar

Line

Pyramid

Scatter

Step

3D appearance

show3D

xOffset

yOffset

The show3D attribute displays the chart in three dimensions. The default value is no.

The xOffset and yOffset attributes specify the amount by which to rotate the chart on a horizontal axis (xOffset) or vertical axis (yOffset). The value 0 is flat (no rotation), -1 and 1 are for a full 90 degree rotation left.

(-1) or right (1). The default value is 0.1

All

Multiple series

showLegend

seriesPlacement

The showLegend attribute lets you display the chart legend when the chart contains more than one series of data. The default value is Yes.

The seriesPlacement attribute specifies the location of each series relative to the others. By default, ColdFusion determines the best placement based on the graph type of each series.

All

Tips

tipStyle

tipBGColor

The tipStyle attribute lets you display a small pop-up window that shows information about the chart element pointed to by the mouse pointer. Options are none, mousedown, or mouseover. The default value is mouseover.

The tipBGColor attribute specifies the background color of the tip window for Flash format only. The default value is white.

All

You can also use the cfchartseries tag to specify attributes of chart appearance. The following table describes these attributes:

Chart characteristic

Attributes used

Description

Chart type

Multiple series

seriesLabel

seriesColor

The seriesLabel attribute specifies the text that displays for the series label.

The seriesColor attribute specifies a single color of the bar, line, pyramid, and so on. For pie charts, the color is that of the first slice. Subsequent slices are automatically colored based on the specified initial color, or use the colorList attribute.

All

Paint

paintStyle

Specifies the way color is applied to a data series. You can specify solid color, raised button, linear gradient fill with a light center and darker outer edge, and gradient fill on lighter version of color. The default value is solid.

All

Data point colors

colorList

A comma-separated list of colors to use for each data point for bar, pyramid, area, horizontalbar, cone, cylinder, step, and pie charts.

You can specify 16 color names, use any valid HTML color format, or specify an 8-digit hexadecimal value to specify the RGB value and transparency. If you use numeric format, use double number signs; for example, blue or ##FF33CC. To specify the color and transparency, use the format ##xxFF33CC, where xx indicates the transparency. The value FF indicates opaque; the value 00 indicates transparent. For the complete list of colors, see Configuring and Administering ColdFusion.

If you specify fewer colors than data points, the colors repeat. If you specify more colors than data points, the extra colors are not used.

Pie

Data markers

markerStyle

Specifies the shape used to mark the data point. Shapes include circle, diamond, letterx, mcross, rcross, rectangle, snow, and triangle. Supported for two-dimensional charts. The default value is rectangle.

Curve

Line

Scatter

Labels

dataLabelStyle

Specifies the way in which the color is applied to the item in the series Styles include None,Value, Rowlabel, Columnlabel, and Pattern.

All

Creating your own chart styles

You can create your own chart styles by doing either of the following:

  • Modifying the chart style XML files

  • Using WebCharts3D to create chart styles

Modifying the chart style XML files

You can modify the chart styles included with ColdFusion to create your own chart styles. The files that contain the style information are XML files located in the cf_root\charting\styles directory. Modify only attributes specified in the file. To specify additional attributes, follow the instructions in the section Using WebCharts3D to create chart styles.

Note: Two XML files exist for each default chart style. For example, the beige style for pie charts is defined in the beige_pie.xml file; the beige style for all other types of charts is defined in the beige.xml file.

  1. Open the XML file that you want to modify, for example beige.xml.

  2. Modify the file contents.

  3. Save the file with a different name; for example myBeige.xml.

Using WebCharts3D to create chart styles

Starting with ColdFusion MX 7, ColdFusion includes the WebCharts3D utility, which you can use to create chart style files.

  1. Start WebCharts3D by double-clicking the webcharts.bat file in the CFusion\charting directory.

  2. (Optional) Open an existing chart.

  3. Make the changes you want to the appearance of the chart.

    Note: To use the chart style file in the cfchart tag, you can only make the modifications indicated in the table that follows this procedure.

  4. Click the XML style tab.

  5. Click the Save button in the lower-right corner.

  6. Specify the name of the file; for example, mystyle.xml.

  7. Specify the directory in which you want to save the chart style file.

    Note: ColdFusion uses the same rules to look for the chart style XML files as it does for files included using the cfinclude tag. For more information, seecfinclude.

  8. Click Save.

The following table lists the attributes of the cfchart and cfchartseries tags and the associated WebCharts3D commands:

Attribute

WebCharts3D command

chartHeight

Drag the chart by handles.

chartWidth

Drag the chart by handles.

dataBackgroundColor

Background: minColor (type must be PlainColor)

font

font: Family (specify only supported fonts)

fontBold

font: check Bold

fontItalic

font: check Italic

fontSize

font: Size

foregroundColor

foreground

gridlines

X-axis: labelcount

labelFormat

Y-axis: LabelFormat: Number | Percent| Currency | Datetime

markerSize

Elements: markerSize

pieSliceStyle

style: solid | slice

rotated

Type Frame chart: Elements: Shape:

scaleFrom

Yaxis: isAbsolute; scaleMin(int)

scaleTo

Yaxis: isAbsolute; scaleMax(int)

seriesPlacement

Elements: place

show3D

is3D

showBorder

Decoration: style (none or simple)?

showLegend

Legend: isVisible

showMarkers

Elements: showMarkers

showXGridlines

Frame: isVGridVisible

showYGridlines

Frame: isHGridVisible

tipbgColor

Popup: background

tipStyle

Popup: show on MouseOver | show on MouseDown | Disabled

url

Elements: action | Series: action

xAxisTitle

X-axis: TitleStyle: text (enter text)

xAxisType

X-axis: type: (category or scale)

xOffset

Frame: xDepth

yAxisTitle

Y-axis: TitleStyle: text (enter text)

yAxisType

Currently has no effect.

yOffset

Frame: yDepth

The following table lists the attributes of the cfchartseries tag and the associated WebCharts3D commands:

Attribute

WebCharts3D command

colorlist

Elements: series: Paint: color

markerStyle

Elements: series: Marker type: Rectangle | Triangle | Diamond | Circle | Letter | MCROSS | Snow | RCROSS

paintStyle

Paint: paint: Plain | Shade | Light

seriesColor

Elements: series: Paint: color

seriesLabel

Elements: series:

type

Type: Pie chart |

Type Frame chart: Elements: Shape: Bar | Line | Pyramid | Area | Curve | Step | Scatter | Cone | Cylinder | Horizontalbar |