This page last changed on Jun 01, 2009 by ggaskell.

The Chart Macro allows you to display a chart based on tabular data. When entering the macro code, you will supply the data and choose the format of the chart.

The chart macro appears as shown in the following screenshot.

Screenshot: The Chart Macro in Confluence

On this page:

Usage with the Macro Browser

To insert the chart macro into a page using the Macro Browser,

  1. Open your desired Confluence page, then click the 'Edit' button. The 'Edit Page' mode opens.
  2. Next, click the Macro Browser icon on the editor toolbar. The Macro Browser will open in the middle of the screen.
  3. In the Macro Browser, type the name of your desired macro into the search box at the top right of the window. Macros with a matching name will appear in the centre pane. Click on the desired macro to see its options screen. Here, you can set the macro parameters then click 'insert' to put the macro into the page.

     4. Once you've found the chart macro, select a type of chart from the parameter settings (listed below).
     5. You will also need to manually enter your chart data as a Wiki markup table into the 'body text' field, like so:

|produce|orange|lemon|grape|pear|
|week 1 |10| 20| 30| 40 |50|
|week 2 |100|200|300|300|400|500|

     6. Click 'Preview' to check that your settings and data are correct.
     7. Finally, click 'insert' to add the chart to your page.

Usage with the Wiki Markup Editor.

Here is a simple example of a pie chart.

What you need to type What you will get
{chart:type=pie|title=Fish Sold}
|| Fish Type || 2004 || 2005 ||
|| Herring | 9,500 | 8,300 |
|| Salmon | 2,900 | 4,200 |
|| Tuna | 1,500 | 1,500 |
{chart}

Here is a simple example of a bar chart.

What you need to type What you will get
{chart:type=bar|title=Fish Sold}
|| Fish Type || 2004 || 2005 ||
|| Herring | 9,500 | 8,300 |
|| Salmon | 2,900 | 4,200 |
|| Tuna | 1,500 | 1,500 |
{chart}

Parameters

Chart Type Parameters | Display Control Parameters | Title and Label Customisation Parameters | Data Specification Parameters | Colour Customisation Parameters | Axis Customisation Parameters | Pie Chart Customisation Parameters | Attachment Parameters

Chart Type Parameters

These parameters determine what type of chart to display and the way the chart looks.

  • type - The type of chart to display. Both standard charts and XY charts are supported. XY charts have numerical x and y axes. The x values may optionally be time based (see the timeSeries parameter). The following chart types are available:
Standard charts
  • pie (default)
  • bar
  • line
  • area
XY plots
  • xyArea
  • xyBar
  • xyLine
  • xyStep
  • xyStepArea
  • scatter
  • timeSeries
Other charts
  • orientation — A bar, line, or area chart will be displayed vertically (y axis is vertical) unless 'orientation=horizontal' is specified.
  • 3D — A pie, bar, or line chart will be shown in 3D if '3D=true' is specified.
  • stacked — A bar or area chart will be shown with stacked values if 'stacked=true' is specified.
  • showShapes — Shapes will be shown at each data point in a line chart unless showShapes=false.
  • opacity — A percentage value between 0 (not visible) and 100 (non-transparent) that determines how opaque the foreground areas and bars are. Defaults are:
    • 75 percent for 3D charts
    • 50 percent for non-stacked area charts
    • 100 percent for all other charts

Display Control Parameters

  • width — The width of the chart in pixels (default is '300').
  • height — The height of the chart in pixels (default is '300').
  • dataDisplay — Default is false to not display the rendered body of the macro (usually the data tables). When dataDisplay=true or dataDisplay=after, the data will be displayed after the chart. When dataDisplay=before, the data will be displayed before the chart.
  • imageFormat — Default is png. Format of generated image. Valid formats are png and jpg. Other formats may be also be valid if installed on your server.

Title and Label Customisation Parameters

  • title — The title of the chart.
  • subTitle — A subtitle for the chart using a smaller font.
  • xLabel — The label to use for the x (domain) axis.
  • yLabel — The label to use for the y (range) axis.
  • legend — A legend will be displayed unless 'legend=false' is specified.

Data Specification Parameters

The data for the chart is taken from tables found when the macro body is rendered. These options control how this data is interpreted. By default, numeric and date values are interpreted according to the Confluence global default language (locale) formats. If conversion fails, other languages defined to Confluence will be tried. Additional conversion options can be specified using the parameters below.

  • tables — Comma separated list of table ids and/or table numbers (starting at 1) contained within the body of the macro that will be used as the data for the chart. Defaults to all first level tables. If data tables are embedded in other tables, then table selection will be required. This occurs when more complex formatting is done (for example using section and column macros). See Macros know to cause problems
  • columns — Comma separated list of column labels and/or column titles and/or column numbers for tables used for chart data. This applies to all tables processed. Defaults to all columns. Columns are enumerated starting at 1. Column label is the text for the column in the header row. Column title is the (html) title attribute for the column in the header row.
  • dataOrientation — The data tables will be interpreted as columns (horizontally) representing domain and x values unless 'dataOrientation=vertical'.
  • timeSeries — If 'true', the x values in an XY plot will be treated as time series data and so will be converted according date formats.
  • dateFormat — For time series data, the date format allows for additional customization of the conversion of data to date values. By default, the Confluence language defined date formats will be used. If a dateFormat is specified, it will be the first format used to interpret date values. Specify a format that matches the format of the time series data. See simple date format.
  • timePeriod — Specify the time period for time series data. Default is 'Day'. This defines the granularity of how the data is interpreted. Valid values are: Day, Hour, Millisecond, Minute, Month, Quarter, Second, Week, Year.
  • language — If provided, the language and country specification will be used to create additional number and date formats to be used for data conversion. This specification will be used before the default languages automatically used. Valid values are 2 character ISO 639-1 alpha-2 codes.
  • country — Used in combination with the language parameter. Valid values are 2 character ISO 3166 codes.
  • forgive — Default is true to try to convert numeric and date values that do not totally match any of the default or user specified formats. Specify forgive=false to enforce strict data format. Data format errors will cause the chart to not be produced.

Colour Customisation Parameters

See the notation guide for details on how to specify colours.

  • bgColor — Colour (default is 'white') to use as the background of the chart.
  • borderColor — Colour of a border around the chart. Default is to not show a border.
  • colors — Comma separated list of colours used to customise category, sections, and series colours.

Axis Customisation Parameters

Depending on the chart type, the range and domain axis may be customised. These values are automatically generated based on the data but can be overridden by specifying one or more more of these parameters.

  • rangeAxisLowerBound — range axis lower bound.
  • rangeAxisUpperBound — range axis upper bound
  • rangeAxisTickUnit — range axis units between axis tick marks
  • rangeAxisLabelAngle — angle for the range axis label in degrees
  • domainAxisLowerBound — domain axis lower bound. For a date axis, this value must be expressed in the date format specified by the dateFormat parameter. (Only used in XY Plots, standard charts will have no effect)
  • domainAxisUpperBound — domain axis upper bound. For a date axis, this value must be expressed in the date format specified by the dateFormat parameter. (Only used in XY Plots, standard charts will have no effect)
  • domainAxisTickUnit — domain axis units between axis tick marks. For a date axis, this value represents a count of the units specified in the timePeriod parameter. The time period unit can be overridden by specifying a trailing character: y for years, M for months, d for days, h for hours, m for minutes, s for seconds, u - milliseconds. (Only used in XY Plots, standard charts will have no effect)
  • domainAxisLabelAngle — angle for the domain axis label in degrees. (Only used in XY Plots, standard charts will have no effect)
  • categoryLabelPosition — allows axis label text position for categories to be customised.
    • up45 - 45 degrees going upward
    • up90 - 90 degrees going upward
    • down45 - 45 degrees going downward
    • down90 - 90 degrees going downward
  • dateTickMarkPosition — placement of the date tick mark.
    • start (default) — tick mark is at the start of the date period.
    • middle — tick mark is in the middle of the date period.
    • end — tick mark is at the end of the date period.

Pie Chart Customisation Parameters

  • pieSectionLabel — Format for how pie section labels are displayed. The default is to show only the pie section key value. The format is a string with special replacement variables:
    • %0% is replaced by the pie section key.
    • %1% is replaced by the pie section numeric value.
    • %2% is replaced by the pie section percent value.
      Example 1: "%0% = %1%" would display something like "Independent = 20"
      Example 2: "%0% (%2%)" would display something like "Independent (20%)"
  • pieSectionExplode — Comma separated list of pie keys that are to be shown exploded. Defaults to no exploded sections. Note: requires jFreeChart version 1.0.3 or higher.

Attachment Parameters

These are advanced options that can be used for chart versioning, to enable automation and to improve performance. Use these options carefully! Normally, the chart image is regenerated each time the page is displayed. These options allow for the generated image to be saved as an attachment and have subsequent access re-use the attachment. This can be useful especially when combined with the Cache Plugin to improve performance. Depending on the options chosen, chart images can be versioned for historical purposes.

  • attachment — Chart image will be saved in a attachment. This advanced capability is for automation or use in combination with the cache macro. For attachment to be used, the user must be authorised to add attachments to the page specified.
    • ^attachmentName.png — The chart is saved as an attachment to the current page.
    • page^attachmentName.png — The chart is saved as an attachment to the page name provided.
    • space:page^attachmentName.png — The chart is saved as an attachment to the page name provided in the space indicated.
  • attachmentVersion — Defines the the versioning mechanism for saved charts.
    • new — (default) Creates new version of the attachment.
    • replace — Replaces all previous versions of the chart. To replace an existing attachment, the user must be authorized to remove attachments for the page specified.
    • keep — Only saves a new attachment if an existing export of the same name does not exist. An existing attachment will not be changed or updated.
  • attachmentComment — Comment used for a saved chart attachment.
  • thumbnail — Default is false. If true, the chart image attachment will be shown as a thumbnail.
Chart Type Parameters | Display Control Parameters | Title and Label Customisation Parameters | Data Specification Parameters | Colour Customisation Parameters | Axis Customisation Parameters | Pie Chart Customisation Parameters | Attachment Parameters

Compatibility With Other Macros

Macros known to be allowed in the body of the chart macro

  • Include Page Macro — to include a page containing data tables
  • SQL Plugin — to generate chart data using SQL select statements, note multiple sql macros are allowed in the same body.
  • CSV Macro — to provide chart data from comma separated values (csv)
  • Java Scripting Plugin — to generate chart data using Java code
  • Excel Plugin — to provide chart data from an Excel spreadsheet
  • Layout Macros — the section and column macros can be used starting with version 1.7

Macros known to cause problem if included in the body of the chart macro

If you use the section, column, scrollbar, or other advanced formatting macros in the body of the chart macro, then you must use the tables parameter to identify the tables that are to be used for chart data. This is due to the fact that these macros produce tables causing the data tables to be lower level sub-tables. The easiest approach is to assign an id to the data table and then explicitly list it in the tables parameter of the chart macro. The id of the table can be set using various macros that have Common table capabilities.

Examples

Time Series Chart

What you need to type
{chart:type=timeSeries|dateFormat=MM/yyyy|timePeriod=Month| dataOrientation=vertical|rangeAxisLowerBound=0|domainaxisrotateticklabel=true}
|| Month || Revenue ||
| 1/2005 | 31.8 |
| 2/2005 | 41.8 |
| 3/2005 | 51.3 |
| 4/2005 | 33.8 |
| 5/2005 | 27.6 |
| 6/2005 | 49.8 |
| 7/2005 | 51.8 |
| 8/2005 | 77.3 |
| 9/2005 | 73.8 |
| 10/2005 | 97.6 |
| 11/2005 | 101.2 |
| 12/2005 | 113.7 |

|| Month || Expenses ||
| 1/2005 | 41.1 |
| 2/2005 | 43.8 |
| 3/2005 | 45.3 |
| 4/2005 | 45.0 |
| 5/2005 | 44.6 |
| 6/2005 | 43.8 |
| 7/2005 | 51.8 |
| 8/2005 | 52.3 |
| 9/2005 | 53.8 |
| 10/2005 | 55.6 |
| 11/2005 | 61.2 |
| 12/2005 | 63.7 |
{chart}
What you will get

XY Line Chart

What you need to type
{chart:type=xyline}
|| || 12 || 14 || 23 ||
| Revenue | 41.1 | 31.8 | 12.4 |
| Expense | 31.1 | 41.8 | 43.6 |
{chart}
What you will get

XY Bar Chart

What you need to type
{chart:type=xybar|opacity=60}
|| || 2005 || 2006 || 2007 ||
| Revenue | 41.1 | 31.8 | 12.4 |
| Expense | 31.1 | 41.8 | 43.6 |
{chart}
What you will get

XY Area Chart

What you need to type
{chart:type=xyarea}
|| || 12 || 14 || 23 ||
| Revenue | 41.1 | 31.8 | 12.4 |
| Expense | 31.1 | 41.8 | 43.6 |
{chart}
What you will get

Area Charts

What you need to type
{chart:type=area|dataDisplay=true|legend=true|width=300|height=300|opacity=50}
|| Satisfaction || 2002 || 2003 || 2004 ||
| Very satisfied | 20 | 23 | 34 |
| Satisfied | 40 | 34 | 23 |
| Disatisfied | 25 | 26 | 25 |
| Very disatisfied | 15 | 17 | 18 |
{chart}
What you will get

Satisfaction 2002 2003 2004
Very satisfied 20 23 34
Satisfied 40 34 23
Disatisfied 25 26 25
Very disatisfied 15 17 18
What you need to type
{chart:type=area|dataDisplay=true|legend=true|width=300|height=300|stacked=true}
|| Satisfaction || 2002 || 2003 || 2004 ||
| Very satisfied | 12 | 23 | 31 |
| Satisfied | 1 | 34 | 36 |
| Disatisfied | 4 | 6 | 22 |
| Very disatisfied | 2 | 7 | 12 |
{chart}
What you will get

Satisfaction 2002 2003 2004
Very satisfied 12 23 31
Satisfied 1 34 36
Disatisfied 4 6 22
Very disatisfied 2 7 12
RELATED TOPICS

Flowchart Macro
Working with Macros

Take me back to the Confluence User Guide.

Document generated by Confluence on Nov 05, 2009 23:35