Chart Macro

The Chart macro allows you to display a chart based on tabular data. When you add the macro to a page, you:

supply the data to be charted by the macro as a table in the placeholder of the macro.
edit the macro parameters in the Macro Browser to configure the format of the chart.

Screenshot 1: A table of data in the Chart macro placeholder

Screenshot 2: The resulting chart

On this page:

Using the Chart Macro

To add the Chart macro to a page:

Edit the page and use autocomplete to add the Chart macro. (Type '{chart}'.)
Enter your chart data as one or more tables in the body of the macro placeholder. (See the screenshot above.)
Click the macro placeholder and choose Edit.
Select a chart type using the Type parameter (see below).
Choose other parameter settings in the macro browser, as described below.
Click Refresh in the 'Preview' area, to check that the chart appears as you expect.
Click Save to add the chart to your page.
Click Save again when you are ready to save the page.

Parameters

Chart Type Parameters

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

Parameter	Default	Description
Type	pie	The type of chart to display. XY charts have numerical x- and y-axes. The x values may optionally be time-based (see the Time Series parameter). Standard — pie, bar, line, area XY Plots — xyArea, xyBar, xyLine, xyStep, xyStepArea, scatter, timeSeries Other — gantt
Display Orientation	vertical	Applies to area, bar and line charts. vertical — y-axis is vertical horizontal — x-axis is vertical
Show in 3D	false	Applies to area, bar and line charts.
Stacked Values	false	Applies to area and bar charts.
Show shapes	true	Applies to line charts. Shapes are shown at each data point.
Opacity	75 percent for 3D charts 50 percent for non-stacked area charts 100 percent for all other charts	A percentage value between 0 (transparent) and 100 (opaque) that determines how opaque the foreground areas and bars are.

Display Control Parameters

Parameter	Default	Description
Width	300	The width of the chart in pixels.
Height	300	The height of the chart in pixels.
Display rendered data	false	Sets whether to display the rendered body of the macro (usually the data tables). By default, the chart data table isn't rendered. before — the data are displayed before the chart. after — the data are displayed after the chart.
Image format	png	The image format to be used for the chart. png jpg

Title and Label Parameters

Parameter	Default	Description
Chart Title	none	The title of the chart.
Chart Subtitle	none	A subtitle for the chart, using a smaller font than for Title.
Horizontal-axis Label	none	The label for the x-axis (domain).
Vertical-axis Label	none	The label for the y-axis (range).
Show Legend	true	Show a legend or key.

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 in Confluence will be tried. Additional conversion options can be specified using the parameters below.

Parameter	Default	Description
Tables	all first level 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. 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).
Columns	all 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. 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.
Content Orientation	horizontal	vertical — data table columns will be interpreted as series. horizontal — data tables rows will be interpreted as series.
Time Series	false	true — the x values in an XY plot will be treated as time series data and so will be converted according to date formats.
Date format	Confluence language defined date formats	For time series data, the date format allows for additional customization of the conversion of data to date values. If a Date format is specified, it will be the first format used to interpret date values. Specify a format that matches the time series data. See simple date format.
Time Period	Day	The time period for time series data. Defines the granularity of how the data is interpreted. Valid values are: Millisecond, Second, Minute, Hour, Day, Week, Month, Quarter, Year.
Language	none	Use in combination with the Country parameter to form a locale. These additional number and date formats will be used for data conversion before the default languages. Valid values are 2 character ISO 639-1 alpha-2 codes.
Country	none	Use in combination with the Language parameter to form a locale. Valid values are 2 character ISO 3166 codes.
Forgive	true	true — the macro tries to convert numeric and date values that do not totally match any of the default or user-specified formats. false — enforce strict data format. Data format errors will cause the chart to not be produced.

Colour Parameters

Colours are specified using hexadecimal notation or HTML colour names.

Parameter	Default	Description
Background Colour	White	Background of the chart.
Border Colour	no border	Border around the chart.
Colours		Comma-separated list of colours used to customise category, sections, and series colours.

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

Parameter	Default	Description
Range Minimum Value	none	Range axis lower bound.
Range Maximum Value	none	Range axis upper bound.
Range Axis Tick Unit	none	Range axis units between axis tick marks.
Range Axis Label Angle	none	Angle for the range axis label in degrees.
Domain Axis Lower Bound	none	Only applies to XY plots. Domain axis lower bound. For a date axis, this value must be expressed in the date format specified by the Date format parameter.
Domain Axis Upper Bound	none	Only applies to XY plots. Domain axis upper bound. For a date axis, this value must be expressed in the date format specified by the Date format parameter.
Domain Axis Tick Unit	none	Only applies to XY plots. Domain axis units between axis tick marks. For a date axis, this value represents a count of the units specified in the Time Period parameter. The Time Period unit can be overridden by specifying a trailing character: y (years), M (months), d (days), h (hours), m (minutes), s (seconds), u (milliseconds).
Domain Axis Label Angle	none	Only applies to XY plots. The angle for the domain axis label, in degrees.
Category Label Position	none	Placement of the axis label text for categories. `up45` — 45 degrees going upward `up90` — 90 degrees going upward `down45` — 45 degrees going downward `down90` — 90 degrees going downward
Date Tick Mark Position	start	Placement of the date tick mark. `start` — 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 Parameters

Parameter

Default

Description

Pie Section Label

Show only the pie section key value

Format for how pie section labels are displayed. The format uses 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%)"

Pie Section Explode

No exploded sections

Comma separated list of pie keys that are to be shown exploded. 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 Pluginto improve performance. Depending on the options chosen, chart images can be versioned for historical purposes.

Parameter	Default	Description
Attachment	none	The name and location with which the chart image will be saved as an attachment. 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.
Attachment Version	new	Defines the the versioning mechanism for saved charts. new — 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.
Attachment Comment	none	Comment used for a saved chart attachment.
Thumbnail	false	true — the chart image attachment will be shown as a thumbnail.

Examples

Pie Chart

Parameters in Macro Browser

Data Table in Macro Placeholder

Rendered Chart

Type

pie

Fish Type	2011
Herring	9,500
Salmon	2,900
Tuna	1,500

Chart Title

Fish Sold 2011

Show Legend

true

Content Orientation

vertical

Bar Chart

Parameters in Macro Browser

Data Table in Macro Placeholder

Rendered Chart

Type

bar

Fish Type	2010	2011
Herring	9,500	8,300
Salmon	2,900	4,200
Tuna	1,500	1,500

Chart Title

Fish Sold

Show Legend

true

3D Bar Chart

Parameters in Macro Browser

Data Table in Macro Placeholder

Rendered Chart

Type

bar

	2009	2010	2011
Revenue	12.4	31.8	41.1
Expense	43.6	41.8	31.1

Show in 3D

true

Opacity

50

Show Legend

true

Time Series Chart

Parameters in Macro Browser

Data Tables in Macro Placeholder

Rendered Chart

Type

Time Series

Month	Revenue
1/2011	31.8
2/2011	41.8
3/2011	51.3
4/2011	33.8
5/2011	27.6
6/2011	49.8
7/2011	51.8
8/2011	77.3
9/2011	73.8
10/2011	97.6
11/2011	101.2
12/2011	113.7

Month	Expenses
1/2011	41.1
2/2011	43.8
3/2011	45.3
4/2011	45.0
5/2011	44.6
6/2011	43.8
7/2011	51.8
8/2011	52.3
9/2011	53.8
10/2011	55.6
11/2011	61.2
12/2011	63.7

Date Format

MM/yyyy

Time Period

Month

Content Orientation

vertical

Range Axis Lower Bound

0

Show Legend

true

XY Line Chart

Parameters in Macro Browser

Data Table in Macro Placeholder

Rendered Chart

Type

xyLine

	12	14	23
Revenue	41.1	31.8	12.4
Expense	31.1	41.8	43.6

Show Legend

true

XY Area Chart

Parameters in Macro Browser

Data Table in Macro Placeholder

Rendered Chart

Type

xyArea

	12	14	23
Revenue	41.1	31.8	12.4
Expense	31.1	41.8	43.6

Show Legend

true

Area Charts

Example 1

Parameters in Macro Browser

Data Table in Macro Placeholder

Rendered Chart

Type

area

Satisfaction	2009	2010	2011
Very satisfied	20	23	34
Satisfied	40	34	23
Dissatisfied	25	26	25
Very dissatisfied	15	17	18

Show Legend

true

Width

300

Height

300

Opacity

50

Example 2

Parameters in Macro Browser

Data Table in Macro Placeholder

Rendered Chart

Type

area

Satisfaction	2009	2010	2011
Very satisfied	12	23	31
Satisfied	1	34	36
Dissatisfied	4	6	22
Very dissatisfied	2	7	12

Show Legend

true

Width

300

Height

300

Stacked Values

true

Gantt Chart

Parameters in Macro Browser

Data Table in Macro Placeholder

Rendered Chart

Type

gantt

Plan	Start	End	Status
Stage 1	6/25/2013	7/10/2013	30%
Stage 2	7/13/2013	11/28/2013	40%
Stage 3	12/1/2013	12/25/2013

Actual	Start	End	Status
Stage 1	6/25/2013	7/26/2013	100%
Stage 2	7/29/2013	12/01/2013	40%
Stage 3	12/10/2013	12/25/2013

Width

300

Height

200

Columns

,,1,2,3,4

Date format

MM/dd/yyyy

Code examples

The following examples are provided for advanced users who want to edit the underlying markup for a Confluence page.

Macro name: chart

Macro body: Accepts rich text, consisting of tables that hold the chart's data.

This macro recognises a large number of parameters, listed here by type for convenience.

Chart type parameters

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

Parameter	Required	Default	Description
`type`	No	`pie`	The type of chart to display. XY charts have numerical x- and y-axes. The x values may optionally be time-based. See the `timeSeries` parameter. Available values: Standard charts `- pie, bar, line, area` XY plots – `xyArea, xyBar, xyLine, xyStep, xyStepArea, scatter, timeSeries` Other charts – `gantt`
`orientation`	No	`vertical`	The display orientation. Applies to area, bar and line charts. Available values: `vertical` – y-axis is vertical `horizontal` – x-axis is vertical
`3D`	No	`false`	Show in three dimensions. Applies to area, bar and line charts.
`stacked`	No	`false`	Stacked values. Applies to area and bar charts.
`showShapes`	No	true	Applies to line charts. Shapes are shown at each data point.
`opacity`	No	75 percent for 3D charts 50 percent for non-stacked area charts 100 percent for all other charts	A percentage value between 0 (transparent) and 100 (opaque) that determines how opaque the foreground areas and bars are.

Chart display parameters

Parameter	Required	Default	Description
`width`	No	`300`	The width of the chart in pixels.
`height`	No	`300`	The height of the chart in pixels.
`dataDisplay`	No	`false`	Determines whether to display the body of the macro, consisting of the data table. By default, the chart data table is not displayed. Available values: false – the data is not displayed. `true` or `after` – the data is displayed after the chart. `before –` the data is displayed before the chart.
`imageFormat`	No	`png`	The image format to be used for the chart. Available values: `png` `jpg`

Chart title and label parameters

Parameter	Required	Default	Description
`title`	No	(None)	The title of the chart.
`subTitle`	No	(None)	A subtitle for the chart.
`xLabel`	No	(None)	The label for the x-axis (domain).
`yLabel`	No	(None)	The label for the y-axis (range).
`legend`	No	`false`	Determines whether to show a legend (key) for the chart.

Chart data parameters

The data for the chart is taken from tables found in the macro body. The parameters below 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 in Confluence will be tried. You can specify additional conversion options using the parameters below.

Parameter	Required	Default	Description
`tables`	No	All first level tables	You can supply a 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. 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).
`columns`	No	All columns	You can supply a 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. 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`	No	`horizontal`	The content orientation. By default, the data tables will be interpreted as columns (horizontally) representing domain and x values. Available values: `vertical` – data table columns will be interpreted as series. `horizontal –` data tables rows will be interpreted as series.
`timeSeries`	No	`false`	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`	No	Confluence language defined date formats	For time series data, the date format allows for additional customisation of the conversion of data to date values. If a `dateFormat` is specified, it will be the first format used to interpret date values. Specify a format that matches the time series data. See simple date format.
`timePeriod`	No	`day`	The time period for time series data. Defines the granularity of how the data is interpreted. Available values: `millisecond, second, minute, hour, day, week, month, quarter, year`
`language`	No	(None)	Use in combination with the `country` parameter to form a locale. These additional number and date formats will be used for data conversion before the default languages. Available values are the two-character ISO 639-1 alpha-2 codes.
`country`	No	(None)	Use in combination with the `language` parameter to form a locale. Valid values are the two-character ISO 3166 codes.
`forgive`	No	`true`	Determines whether the macro will forgive (allow) some data formatting errors. Available values: `true` — the macro tries to convert numeric and date values that do not totally match any of the default or user-specified formats. `false` — the macro enforces strict data formatting. If there are data format errors, the chart will not be produced.

Chart colour parameters

Colours are specified using hexadecimal notation or HTML colour names.

Parameter	Required	Default	Description
`bgColor`	No	White	Background colour of the chart.
`borderColor`	No	No border	Colour of the border around the chart.
`colors`	No		A comma-separated list of colours used to customise the colours of categories, sections, and series.

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

Parameter	Required	Default	Description
`rangeAxisLowerBound`	No	(None)	Minimum value for the range axis.
`rangeAxisUpperBound`	No	(None)	Maximum value for the range axis.
`rangeAxisTickUnit`	No	(None)	Range axis units between axis tick marks.
`rangeAxisLabelAngle`	No	(None)	Angle for the range axis label in degrees.
`domainAxisLowerBound`	No	(None)	Only applies to XY plots. Domain axis lower bound. For a date axis, this value must be expressed in the date format specified by the `dateFormat` parameter.
`domainAxisUpperBound`	No	(None)	Only applies to XY plots. Domain axis upper bound. For a date axis, this value must be expressed in the date format specified by the `dateFormat` parameter.
`domainAxisTickUnit`	No	(None)	Only applies to XY plots. 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 `timePeriod` unit can be overridden by specifying a trailing character: `y` (years), `M` (months), `d` (days), `h` (hours), `m` (minutes), `s` (seconds), `u` (milliseconds).
`domainAxisLabelAngle`	No	(None)	Only applies to XY plots. The angle for the domain axis label, in degrees.
`categoryLabelPosition`	No	(None)	Placement of the axis label text for categories. Available values: `up45` — 45 degrees going upward `up90` — 90 degrees going upward `down45` — 45 degrees going downward `down90` — 90 degrees going downward
`dateTickMarkPosition`	No	`start`	Placement of the date tick mark. Available values: `start` — 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 Parameters

Parameter Required Default Description

pieSectionLabel

No

Show only the pie section key value

Formatof pie section labels. The format uses 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: To display something like 'Independent = 20':

%0% = %1%

Example 2: To display something like 'Independent (20%)':

%0% (%2%)

pieSectionExplode No No exploded sections A comma-separated list of pie keys that are to be shown exploded. Note: requires jFreeChart version 1.0.3 or higher.

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

Parameter	Required	Default	Description
`attachment`	No	(None)	The name and location where the chart image will be saved as an attachment. The user must be authorised to add attachments to the page specified. Available syntax for this parameter: `^attachmentName.png` — the chart is saved as an attachment to the current page. `page name^attachmentName.png` — the chart is saved as an attachment to the page name provided. `spacekey:page name^attachmentName.png` — the chart is saved as an attachment to the page name provided in the space indicated.
`attachmentVersion`	No	`new`	Defines the the versioning mechanism for saved charts. Available values: `new` — creates new version of the attachment. `replace` — replaces all previous versions of the chart. To replace an existing attachment, the user must be authorised 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`	No	(None)	Comment used for a saved chart attachment.
`thumbnail`	No	`false`	If `true`, the chart image attachment will be shown as a thumbnail (small, expandable) image.

Storage format example

Below is a simple example of a pie chart. See more examples in Storage Format Examples for Chart Macro.

<ac:structured-macro ac:name="chart">
  <ac:parameter ac:name="title">Fish Sold</ac:parameter>
  <ac:parameter ac:name="type">pie</ac:parameter>
  <ac:rich-text-body>
    <table>
      <tbody>
        <tr>
          <th>
            <p>Fish Type</p>
          </th>
          <th>
            <p>2004</p>
          </th>
          <th>
            <p>2005</p>
          </th>
        </tr>
        <tr>
          <th>
            <p>Herring</p>
          </th>
          <td>
            <p>9,500</p>
          </td>
          <td>
            <p>8,300</p>
          </td>
        </tr>
        <tr>
          <th>
            <p>Salmon</p>
          </th>
          <td>
            <p>2,900</p>
          </td>
          <td>
            <p>4,200</p>
          </td>
        </tr>
        <tr>
          <th>
            <p>Tuna</p>
          </th>
          <td>
            <p>1,500</p>
          </td>
          <td>
            <p>1,500</p>
          </td>
        </tr>
      </tbody>
    </table>
  </ac:rich-text-body>
</ac:structured-macro>

Wiki markup example

Below is a simple example of a pie chart. See more examples in Wiki Markup Examples for Chart Macro.

{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}

Page tree

Chart Macro

Using the Chart Macro

Parameters

Chart Type Parameters

Display Control Parameters

Title and Label Parameters

Data Specification Parameters

Colour Parameters

Axis Parameters

Pie Chart Parameters

Attachment Parameters

Examples

Pie Chart

Bar Chart

3D Bar Chart

Time Series Chart

XY Line Chart

XY Area Chart

Area Charts

Example 1

Example 2

Gantt Chart

Code examples

Chart type parameters

Chart display parameters

Chart title and label parameters

Chart data parameters

Chart colour parameters

Chart axis parameters

Pie chart Parameters

Chart attachment parameters

Storage format example

Wiki markup example