Formatting Charts


ColdFusion supports numerous options for fine-tuning and controlling the look of generated charts, both via skins, and via explicitly specified attributes.

Using Skins

Skins are XML files that contain chart color schemes. The following default skins are provided with ColdFusion:

  • beige

  • blue

  • default

  • red

  • silver

  • yellow

These skins are located in {cfusion root}/charting/styles, and you may define additional skins simply by placing them in these folder. Skins contain:

  • Colors to be used

  • 3D effect details

  • Font information

  • Label formatting

  • Animation effects and timings

  • …and more

To use a skin, simply specify its name (minus the .xml extension) in the <cfchart style=""> attribute.

NOTE

There are two skins for each defined skin, one for pie charts and one for all other charts. These are identically named, except that the pie chart skin has _pie in it's name, for example, red.xml and red_pie.xml.


Controlling Fonts and Colors

ColdFusion provides a number of formatting attributes that you can use to control fonts, colors, and borders. Some of the attributes are applied at the <cfchart> level and others at the <cfchartseries> level, as listed in Table 20.3 and Table 20.4, respectively.

Table 20.3. <cfchart> Formatting Options

ATTRIBUTE

DESCRIPTION

showborder

Whether a border should be drawn around the entire chart. The default is No.

showlegend

Whether to display a legend that shows the meaning of each color used in the graph. This is applicable only to pie charts, or charts that use more than one <cfchartseries> tag. The default is Yes.

backgroundcolor

The background color of the portion of the chart that contains the actual graph (that is, excluding the space set aside for axis labels and legends).

databackgroundcolor

The background color of the space set aside for axis labels and legends (everywhere except the part where the actual graph is shown).

tipbgcolor

The background color for the pop-up tip window that appears when you hover the pointer over a data point.

foregroundcolor

The foreground color to use throughout the chart. This controls the color of all text in the chart, as well as the lines used to draw the x- and y-axes, the lines around each bar or pie slice, and so on.

font

The font to use for text in the chart, such as legends and axis labels. In ColdFusion MX, you can choose between arial, times, and courier. In addition, you can choose arialunicodeMS, which you should use when using double-byte character sets. The default is arial.

fontsize

The size of the font, expressed as a number. The default is 11.

fontbold

Whether text is displayed in bold. The default is No.

fontitalic

Whether text is displayed in italics. The default is No.

tipstyle

Optional. Can be set to mouseOver (the default), mouseDown, or off. By default, a hint or tip message will display when the user hovers her pointer over a data point in a graph (an example of this is shown in Figure 25.1). The tip message includes the label and value of the data point, as well as the series label, if given (see Table 25.5). If you want the tip to be shown only when the user clicks a data point, you can use tipstyle="mouseDown", but this works only if format="flash". If you don't want any tip to be shown at all, use tipstyle="off".

pieslicestyle

Relevant only for pie charts. If sliced (the default) is used, the pie is shown with its slices separated by white space (this effect is sometimes called exploded). If solid is used, the pie is shown with its slices together in a circle, the way you would normally think of a pie chart. Unfortunately, there is no way to explode just one slice at a time, which is a common way to present pie charts. In general, you will probably want to use pieslicestyle="solid".


Table 20.4. <cfchartseries> Formatting Options

ATTRIBUTE

DESCRIPTION

seriescolor

A color to use for the main element of the data series.

serieslabel

A label or title for the data series.

paintstyle

A style to use when filling in solid areas on the chart for this series. The default is plain, which uses solid colors. You can also provide raise, which gives each area a raised, buttonlike appearance; shade, which shades each area with a gradient fill, or light, which is a lighter version of shade.

colorlist

Relevant for pie charts only. A comma-separated list of colors to use for the slices of the pie. The first slice will have the first color in the list, the second slice will have the second color, and so on.

markerstyle

Relevant only for line, curve, and scatter charts. The look of the marker that appears at each data point. Can be set to rectangle (the default), triangle, diamond, circle, letter, mcross, snow, or rcross.


NOTE

All of the attributes that control color can accept Web-style hexadecimal color values, such as FFFFFF for white or 0000FF for blue. In addition, any of the following named colors can be used: Aqua, Black, Blue, Fuchsia, Gray, Green, Lime, Maroon, Navy, Olive, Purple, Red, Silver, Teal, White, and Yellow.


Listing 16.4 and Figure 16.4 (below) show how some of these formatting attributes can be combined to improve the appearance of the bar charts you have seen so far.

Controlling Grid Lines and Axis Labels

One of the most important aspects of nearly any chart are the numbers and labels that surround the actual graphic on the x- and y-axes. ColdFusion provides you with a number of options for controlling the scale of each axis (that is, the distance between the highest and lowest values that could be plotted on the chart), and for controlling how many different numbers are actually displayed along the axes.

Table 20.5 shows the <cfchart> attributes related to grid lines and axis labels.

Table 20.5. <cfchart> Options for Grid Lines and Labels

ATTRIBUTE

DESCRIPTION

scalefrom

The lowest number to show on the y-axis. For instance, if you want one of the budget chart examples shown previously to start at $20,000 instead of $0, you can do so with scalefrom="20000".

scaleto

The highest number to show on the y-axis. So, if the highest budget shown in the budget chart examples is $750,000, providing scaleto="1000000" will cause the scale to go all the way up to 1 million, even though there aren't any data points that go up that high. The result is extra "empty space" above the highest value, giving the viewer the sense that the values plotted in the chart could have been higher than they actually are.

gridlines

The number of grid lines to show for the data axis (generally the y-axis). This also affects the number of labeled tick marks along the axis. If you don't provide a value, ColdFusion attempts to use a sensible default value based on the size of the graph. For instance, in Figure 25.2 there are ten grid lines and tick marks (one for 0, one for 83,300, and so on), which seems about right.

showygridlines

Whether to display grid lines for the y-axis. On most types of charts, these grid lines generally make it easier to understand what the value is for each piece of data. These grid lines are shown in Figure 25.1 (the horizontal lines) and Figure 25.2 (the vertical lines). The default is Yes.

showxgridlines

Whether to display grid lines for the x-axis. The default is No.

sortxaxis

Sorts the data in the x-axis (that is, the labels) alphabetically. In general, I recommend that you use order by to reorder the records within a normal <cfquery> tag, before your code gets to the <cfchart> tag; that approach will be much more flexible (see the "Sorting the Data First" section earlier in this chapter).

labelformat

The format for the labels along the y-axis (in our examples so far, the labels that show the increasing amounts of money). You can set this to number (the default), currency (which on English systems adds a dollar sign [$]), percent (which multiplies by 100 and adds a percent sign [%]), or date (appropriate only if the data you are plotting are dates).


NOTE

You can't adjust the scale in such a way that it would obscure or chop off any of the actual data being shown in the chart. If your scalefrom value is higher than the lowest data point on the graph, ColdFusion will use the data point's value instead. For instance, if the lowest budget being plotted in one of the budget chart examples is $34,000 and you provide scalefrom="50000", ColdFusion will start the scale at $34,000. The inverse is also true; if you provide a scaleto value that is lower than the highest data point, that point's value will be used instead.


NOTE

When providing hexadecimal color values, the traditional number sign (#) is optional. If you provide it, though, you must escape the # by doubling it, so ColdFusion doesn't think you are trying to reference a variable. In other words, you could provide backgroundcolor="99DDDD" or backgroundcolor="##99DDDD" as you prefer, but not backgroundcolor= "#99DDDD".




Macromedia ColdFusion MX 7 Certified Developer Study Guide
Macromedia ColdFusion MX 7 Certified Developer Study Guide
ISBN: 0321330110
EAN: 2147483647
Year: 2004
Pages: 389
Authors: Ben Forta

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net