Controlling chart appearance

Use the cfchart and cfchartseries tags to customize the appearance of your charts.

Common chart characteristics

You can optionally specify the following characteristics to cfchart on all types of charts:
Chart characteristic

Attributes used

Description
File type
format
Whether to send the chart to the user as a JPG, PNG, or Flash Movie (.swf) file. Flash is the default format.
Dimensions
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.
Column labels
sortXAxis
Specifies to display the column labels along the x-axis in alphabetical order. The default is no.
Foreground and background 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 or use any valid HTML color format. If you use the numeric format, you must use double pound signs, for example, blue or ##FF33CC. For the complete list of colors, see Administering ColdFusion MX.
Border
showBorder
Specifies to draw a border around the chart. The border color is the same as specified by the foregroundColor attribute. Default is no.
Labels
font
fontSize
fontBold
frontItalic
labelFormat
xAxisTitle
yAxisTitle
font specifies the font for all text. Default is Arial. If you are using a double-byte character set on UNIX, or using a double-byte character set on Windows with a file type of Flash, you must specify ArialUnicodeMs as the font.
fontSize speciofies an Integer font size used for all text. Default is 11.
fontBold specifies to display all text as bold. Default is no.
fontItalic specifies to display all text as italic. Default is no.
labelFormat specifies the format of the y-axis labels, number, currency, percent, or date. Default is number.
xAxisTitle and yAxisTitle specify the title for each axis.
3-D Appearance
show3D
xOffset
yOffset
show3D displays the chart in 3-D. Default is no.
xOffset and yOffset specify the amount to which the chart should be rotated on a horizontal axis (xOffset) or vertical axis (yOffset). 0 is flat (no rotation), -1 and 1 are for a full 90 degree rotation left (-1) or right (1). Default is .1
Rotation
rotated
Rotates the entire chart 90 degrees. Set to yes to create a horizontal chart, such as a horizontal bar chart. Default is no.
Multiple series
showLegend
seriesPlacement
showLegend specifies to display the chart's legend when the chart contains more than one series of data. Default is yes.
seriesPlacement 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.
Tips
tipStyle
tipBGColor
tipStyle specifies to display a small popup window that shows information about the chart element pointed to by the curser. Options are none, mousedown, or mouseover. Default is mouseover.
tipBGColor specifies the background color of the tip window for Flash format only. Default is white.
Markers
showMarkers
markerSize
showMarkers specifies to show markers at the data points for 2-D line, curve, and scatter charts. Default is yes.
markerSize specifies an integer number of pixels for the marker size. ColdFusion determines default.

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

Attributes used

Description
Multiple series
seriesLabel
seriesColor
seriesLabel specifies the text displayed for the series label.
seriesColor specifies a single color of the bar, line, pyramid, and so on. For pie charts, this is the first slice's color. Subsequent slices are automatically colored based on the specified initial color, or use the colorList attribute.
Paint
paintStyle
Specifies the way color is applied to a data series. You can specify solid color, buttonized look, linear gradient fill with a light center and darker outer edge, and gradient fill on lighter version of color. Default is solid.
Data markers
markerStyle
For line, curve, and scatter charts, specifies the shape used to mark the data point. Supported for 2-dimensional charts. Default is rectangle.

Setting x-axis and y-axis characteristics

You can specify the following additional characteristics to control the look of the x-axis and y-axis of charts, except for pie charts:
Chart
characteristic

Attributes used

Description
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.
Grid lines
showXGridlines
showYGridlines
gridLines
showXGridlines and showYGridlines specify to display x-axis and y-axis grid lines. Default no for x-axis gridlines, and yes for y-axis gridlines.
gridLines 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. A value of 0 (the default) means no grid lines.

Creating a bar chart

The example in the following procedure adds a title to the bar chart and changes its appearance from the default, flat look, to a 3-D look. It adds grid lines, sets the maximum y-axis value to 100,000, and uses a custom set of colors.

To enhance the bar chart:

  1. Open the chartdata.cfm file in your editor.
  2. Edit the cfchart tag so that it appears as follows:
    <!--- Bar chart, from Query of Queries --->
    <cfchart 
    
    scaleTo = 100000
    fontSize=16
    gridLines = 4 
    show3D="yes"
  >

  <cfchartseries 
    type="bar" 
    query="DeptSalaries" 
    valueColumn="AvgByDept" 
    itemColumn="Dept_Name"
    />

</cfchart>
  • Save the file.
  • Return to your browser and enter the following URL to view chartdata.cfm:

    http://127.0.0.1/myapps/chartdata.cfm

  • Reviewing the code

    The following table describes the highlighted code and its function:
    Code
    Description
    scaleTo = 100000
    
    Set the maximum value of the vertical axis to 100000. The minimum value is the default, 0.
    fontSize=16
    
    Make the point size of the labels 16 points.
    gridLines = 4
    
    Display four grid lines between the top and bottom of the chart.
    show3D = "yes"
    
    Show the chart in 3-D.

    Setting pie chart characteristics

    You can specify the following additional characteristics for pie charts:
    Chart characteristic
    Attributes used
    Description
    Slice style
    (cfchart tag)
    pieSliceStyle
    Display pie chart as solid or sliced. Default is sliced.
    Data point colors
    (cfchartseries tag)
    colorList
    A comma-separated list of colors to use for each pie slice.
    You can specify 16 color names or use any valid HTML color format. If you use the numeric format, you must use double pound signs, for example, blue or ##FF33CC. For the complete list of colors, see Administering ColdFusion MX.
    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.

    The example in the following procedure adds a pie chart to the page.

    To create a pie chart:

    1. Open chartdata.cfm in your editor.
    2. Edit the DeptSalaries query and the cfloop code so that it appears as follows:
      <!--- A query to get statistical data for each department. --->
      <cfquery dbtype = "query" name = "DeptSalaries">
        SELECT 
          Dept_Name,
          SUM(Salary) AS SumByDept,
          AVG(Salary) AS AvgByDept
        FROM GetSalaries
        GROUP BY Dept_Name
      </cfquery>
      
      <!--- Reformat the generated numbers to show only thousands --->
      <cfloop index="i" from="1" to="#DeptSalaries.RecordCount#">
        <cfset DeptSalaries.SumByDept[i]=Round(DeptSalaries.SumByDept[i]/
      1000)*1000>
        <cfset DeptSalaries.AvgByDept[i]=Round(DeptSalaries.AvgByDept[i]/
      1000)*1000>
      </cfloop>
      
    3. Add the following cfchart tag:
      <!--- Pie chart, from DeptSalaries Query of Queries --->
      <cfchart 
          tipStyle="mousedown" 
          font="Times"
          fontsize=14
          fontBold="yes"
          backgroundColor = "##CCFFFF"
          show3D="yes"
          >
          
        <cfchartseries 
          type="pie" 
          query="DeptSalaries" 
          valueColumn="SumByDept" 
          itemColumn="Dept_Name" 
          colorlist="##6666FF,##66FF66,##FF6666,##66CCCC"
          />
      </cfchart>
      <br>
      
    4. Save the file.
    5. Return to your browser and enter the following URL to view chartdata.cfm:

      http://127.0.0.1/myapps/chartdata.cfm

      The following figure appears:

      A pie chart

    Reviewing the code

    The following table describes the highlighted code and its function:
    Code
    Description
    SUM(Salary) AS SumByDept,
    
    In the DeptSalaries query, add a SUM aggregation function to get the sum of all salaries per department.
    <cfset DeptSalaries.SumByDept[i]=
      Round(DeptSalaries.SumByDept[i]/
      1000)*1000>
    
    In the cfloop tag, round the salary sums to the nearest thousand.
    <cfchart 
      tipStyle="mousedown" 
      font="Times"
      fontBold="yes"
      backgroundColor = "##CCFFFF"
      show3D="yes"
      >
    
    Show a tip only when a user clicks on the chart, display text in Times Bold font, set the background color to light blue, and display the chart in 3-D.
    <cfchartseries 
      type="pie" 
      query="DeptSalaries" 
      valueColumn="SumByDept" 
      itemColumn="Dept_Name" 
      colorlist=
        "##6666FF,##66FF66,##FF6666,##66CCCC"
    />
    
    Create a pie chart using the SumByDept salary sum values from the DeptSalares query.
    Use the contents of the Dept_Name column for the item labels displayed in the chart legend.
    Get the pie slice colors from a custom list, which uses hexadecimal color numbers. The double pound signs prevent ColdFusion from trying to interpret the color data as variable names.

    Creating an area chart

    The example in the following procedure adds an area chart showing the average salary by start date to the salaries analysis page. It shows the use of a second query of queries to generate a new analysis of the raw data from the GetSalaries query. It also shows the use of additional cfchart attributes.

    To create an area chart:

    1. Open chartdata.cfm your editor.
    2. Edit the GetSalaries query so that it appears as follows:
      <!-- Get the raw data from the database. -->
      <cfquery name="GetSalaries" datasource="CompanyInfo">
        SELECT Departmt.Dept_Name, 
          Employee.StartDate,
          Employee.Salary
        FROM Departmt, Employee
        WHERE Departmt.Dept_ID = Employee.Dept_ID
      </cfquery>
      
    3. Add the following code before the html tag:
      <!--- Convert start date to start year. --->
      <!--- You must explicitly convert the date to a number for the query to work --->
      <cfloop index="i" from="1" to="#GetSalaries.RecordCount#">
      <cfset GetSalaries.StartDate[i]=NumberFormat(DatePart("yyyy", GetSalaries.StartDate[i]) ,9999)>
      </cfloop>
      
      <!--- Query of Queries for average salary by start year --->
      <cfquery dbtype = "query" name = "HireSalaries">
        SELECT 
          StartDate,
          AVG(Salary) AS AvgByStart
        FROM GetSalaries
        GROUP BY StartDate
      </cfquery>
      
      <!--- Round average salaries to thousands ---> 
      <cfloop index="i" from="1" to="#HireSalaries.RecordCount#">
        <cfset HireSalaries.AvgByStart[i]=Round(HireSalaries.AvgByStart[i]/1000)*1000>
      </cfloop>
      
    4. Add the following cfchart tag before the end of the body tag block:
      <!--- Area-style Line chart, from HireSalaries Query of Queries --->
      <cfchart 
          chartWidth=400
          BackgroundColor="##FFFF00"
          show3D="yes"
        >
        <cfchartseries
          type="area" 
          query="HireSalaries" 
          valueColumn="AvgByStart" 
          itemColumn="StartDate"
         />
      </cfchart>
      <br>
      
    5. Save the page.
    6. Return to your browser and enter the following URL to view chartdata.cfm:

      http://127.0.0.1/myapps/chartdata.cfm

    Reviewing the code

    The following table describes the highlighted code and its function:
    Code
    Description
    Employee.StartDate,
    
    Add the employee start date to the data in the GetSalaries query.
    <cfloop index="i" from="1"
        to="#GetSalaries.RecordCount#">
      <cfset GetSalaries.StartDate[i]=
      NumberFormat(DatePart("yyyy",
      GetSalaries.StartDate[i]) ,9999)>
    </cfloop>
    
    Use a cfloop tag to extract the year of hire from each employee's hire data, and convert the result to a four-digit number.
    <cfquery dbtype = "query" name =
    "HireSalaries">
      SELECT 
          StartDate,
        AVG(Salary) AS AvgByStart
      FROM GetSalaries
      GROUP BY StartDate
    </cfquery>
    
    Create a second query from the GetSalaries query. This query contains the average salary for each start year.
    <cfloop index="i" from="1"
       to="#HireSalaries.RecordCount#">
      <cfset HireSalaries.AvgByStart[i] 
      =Round(HireSalaries.AvgByStart[i]
      /1000)*1000>
    </cfloop>
    
    Round the salaries to the nearest thousand.
    <cfchart 
        chartWidth=400
        BackgroundColor="##FFFF00"
        show3D="yes" >
      <cfchartseries
        type="area" 
        query="HireSalaries" 
        valueColumn="AvgByStart" 
        itemColumn="StartDate"
       />
    </cfchart>
    
    Create a line chart using the HireSalaries query. Chart the average salaries against the start date.
    Limit the chart width to 400 pixels, show the chart in 3-D, and set the background color to white.

    Setting curve chart characteristics

    Curves use the attributes already discussed. However, you should be aware that curve charts require a large amount of processing to render. For fastest performance, create them offline, write them to a file or variable, then reference them in your application pages. For information on creating offline charts, see "Writing a chart to a variable".

    Comments