Chart Macro

Still need help?

The Atlassian Community is here for you.

Ask the community

This macro is available in Confluence Server and Data Center. Learn about the macros available in Confluence Cloud.

Add the Chart macro to a page to display a chart based on data in a table on the same page, or from an attached file.

This is great for showing a simple visualisation of data on the page. 


On this page:

Screenshot: Page with two chart macros. 

Want to display information from Jira on your page? Check out the Jira Chart Macro.

Add the Chart macro to your page

To add the Chart macro to a page:

  1. From the editor toolbar, choose Insert > Other Macros.
  2. Choose Chart from the Visuals and images category.
  3. Choose Insert
  4. Enter your chart data as one or more tables in the body of the macro placeholder. See the examples later in this page for more info.
  5. Click the macro placeholder and choose Edit.
  6. Select a chart type using the Type parameter (see below).
  7. Choose other parameter settings in the macro browser, as described below.
  8. Click Refresh in the 'Preview' area, to check that the chart appears as you expect.
  9. Click Save to add the chart to your page.

You can then publish your page to see the macro in action. 

Screenshot: Two Chart macros in the editor, containing the data for a pie chart and stacked chart. 

Change the macro parameters

Macro parameters are used to change the behaviour of a macro.

To change the macro parameters:

  1. In the editor, click the macro placeholder and choose Edit.
  2. Update the parameters as required then choose Insert.

Here's a list of the parameters available in this macro. 

Chart Type Parameters

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

ParameterDefaultDescription
Typepie

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 Orientationvertical

Applies to area, bar and line charts.

    • vertical — y-axis is vertical
    • horizontal — x-axis is vertical
Show in 3Dfalse

Applies to area, bar and line charts.

Stacked ValuesfalseApplies to area and bar charts.
Show shapestrueApplies 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

ParameterDefaultDescription
Width300The width of the chart in pixels. The maximum width is limited by the confluence.chart.macro.width.max system property.
Height300The height of the chart in pixels. The maximum height is limited by the confluence.chart.macro.height.max system property.
Display rendered datafalse

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 formatpng

The image format to be used for the chart.

    • png
    • jpg

Title and Label Parameters

ParameterDefaultDescription
Chart TitlenoneThe title of the chart.
Chart SubtitlenoneA subtitle for the chart, using a smaller font than for Title.
Horizontal-axis LabelnoneThe label for the x-axis (domain).
Vertical-axis LabelnoneThe label for the y-axis (range).
Show LegendtrueShow 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.

ParameterDefaultDescription
Tablesall first level tablesComma 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).
Columnsall columnsComma 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 Orientationhorizontal
    • vertical — data table columns will be interpreted as series.
    • horizontal — data tables rows will be interpreted as series.
Time Seriesfalse
    • 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 formatConfluence language defined date formatsFor 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 PeriodDayThe 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.
LanguagenoneUse 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.
CountrynoneUse in combination with the Language parameter to form a locale. Valid values are 2 character ISO 3166 codes.
Forgivetrue
    • 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.

Color Parameters

Colors are specified using hexadecimal notation or HTML color names.

ParameterDefaultDescription
Background ColorWhiteBackground of the chart.
Border Colorno borderBorder around the chart.
Colors
Comma-separated list of colors used to customize category, sections, and series colors.

Axis Parameters

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

ParameterDefaultDescription
Range Minimum ValuenoneRange axis lower bound.
Range Maximum ValuenoneRange axis upper bound.
Range Axis Tick UnitnoneRange axis units between axis tick marks.
Range Axis Label AnglenoneAngle for the range axis label in degrees.
Domain Axis Lower BoundnoneOnly 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 BoundnoneOnly 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 UnitnoneOnly 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 noneOnly 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

ParameterDefaultDescription
Pie Section LabelShow only the pie section key valueFormat 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 ExplodeNo exploded sectionsComma 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.

ParameterDefaultDescription
AttachmentnoneThe name and location with which the chart image will be saved as an attachment. The user must be authorized 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 Versionnew

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 Commentnone Comment used for a saved chart attachment.
Thumbnailfalse
    •  true — the chart image attachment will be shown as a thumbnail.

Pie chart

Here's an example of a pie chart. 

To create this chart, we set these parameters in the macro browser:

  • Type: pie
  • Chart title: Fish sold in 2011
  • Show legend: true
  • Content orientation: vertical

and added this table in the macro body:

Fish Type

2011

Herring

9,500

Salmon

2,900

Tuna

1,500

Bar chart

Here's an example of a bar chart. 

To create this chart, we set these parameters in the macro browser:

  • Type: bar
  • Chart title: Fish sold
  • Show legend: True

and added this table in the macro body:

Fish Type

2010

2011

Herring

9,500

8,300

Salmon

2,900

4,200

Tuna

1,500

1,500

3D Bar chart

Here's an example of a 3D bar chart. 

  To create this chart, we set these parameters in the macro browser:

  • Type: bar
  • Show in 3D: true
  • Opacity: 50
  • Show legend: true

and added this table in the macro body:

2009

2010

2011

Revenue

12.4

31.8

Expense

43.6

41.8

Time series chart

Here's an example of a Time series chart. 

  


To create this chart, we set these parameters in the macro browser:

  • Type: Time series
  • Date formatMM/yyyy
  • Time period: Month
  • Content orientation: vertical
  • Range axis lower bound: 0
  • Show legend: true

and added these two tables in the macro body:

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

XY Line Chart

Here's an example of a XY Line chart. 

  

To create this chart, we set these parameters in the macro browser:

  • Type: xyLine
  • Show legend: true

and added this table in the macro body:


12

14

23

Revenue

41.1

31.8

12.4

Expense

31.1

41.8

43.6

XY Area Chart

Here's an example of an XY Area chart. 

To create this chart, we set these parameters in the macro browser:

  • Type: xyArea
  • Show legend: true

and added this table in the macro body:


12

14

23

Revenue

41.1

31.8

12.4

Expense

31.1

41.8

43.6

Area chart

Here's an example of an area chart. 

To create this chart, we set these parameters in the macro browser:

  • Type: area
  • Show legend: true
  • Width: 300
  • Height: 300
  • Opacity: 50

and added this table in the macro body:

Satisfaction

2009

2010

2011

Very satisfied

20

23

34

Satisfied

40

34

23

Dissatisfied

25

26

25

Very dissatisfied

15

17

18

Stacked area chart

Here's another example of an Area chart. 

  

To create this chart, we set these parameters in the macro browser:

  • Type: area
  • Show legend: true
  • Width: 300
  • Height: 300
  • Stacked values: true 

and added this table in the macro body:

Satisfaction

2009

2010

2011

Very satisfied

12

23

31

Satisfied

1

34

36

Dissatisfied

4

6

22

Very dissatisfied

2

7

12

Gantt chart

Here's an example of a Gantt chart. 

  

To create this chart, we set these parameters in the macro browser:

  • Type: gantt
  • Width: 300 
  • Height: 200 
  • Columns:  ,,1,2,3,4   (note the two commas to start)
  • Date formatMM/dd/yyyy

and added these two tables in the macro body:

PlanStartEndStatus
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

ActualStartEndStatus
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


(info) You must include the two leading commas in the column parameter (for example ,,1,2,3,4) for the chart to be created correctly. 

Other ways to add this macro

Add this macro as you type

Type followed by the start of the macro name, to see a list of macros. 

Add this macro using wiki markup

This is useful when you want to add a macro outside the editor, for example as custom content in the sidebar, header or footer of a space.

Macro name: chart

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

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}

This macro recognizes a large number of parameters, listed here by type.

See all parameters...

Chart type parameters

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

ParameterRequiredDefaultDescription
typeNopie

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 plotsxyArea, xyBar, xyLine, xyStep, xyStepArea, scatter, timeSeries
  • Other chartsgantt
orientationNovertical

The display orientation. Applies to area, bar and line charts.

Available values:

  • vertical –  y-axis is vertical
  • horizontal –  x-axis is vertical
3DNofalse

Show in three dimensions. Applies to area, bar and line charts.

stackedNofalseStacked values. Applies to area and bar charts.
showShapesNotrueApplies to line charts. Shapes are shown at each data point.
opacityNo
  • 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

ParameterRequiredDefaultDescription
widthNo300The width of the chart in pixels.
heightNo300The height of the chart in pixels.
dataDisplayNofalse

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

The image format to be used for the chart.

Available values:

  • png
  • jpg

Chart title and label parameters

ParameterRequiredDefaultDescription
titleNo(None)The title of the chart.
subTitleNo(None)A subtitle for the chart.
xLabelNo(None)The label for the x-axis (domain).
yLabelNo(None)The label for the y-axis (range).
legendNofalseDetermines 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.

ParameterRequiredDefaultDescription
tablesNoAll first level tablesYou 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).
columnsNoAll columnsYou 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 Nohorizontal

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 Nofalse

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 NoConfluence language defined date formatsFor time series data, the date format allows for additional customization 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 Noday

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

languageNo(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.

countryNo(None)Use in combination with the language parameter to form a locale. Valid values are the two-character ISO 3166 codes.
forgiveNotrue

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 color parameters

Colors are specified using hexadecimal notation or HTML color names.

ParameterRequiredDefaultDescription
bgColor NoWhiteBackground color of the chart.
borderColor NoNo borderColor of the border around the chart.
colorsNo
A comma-separated list of colors used to customize the colors of categories, sections, and series.

Chart axis parameters

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

ParameterRequiredDefaultDescription
rangeAxisLowerBound No(None)Minimum value for the range axis.
rangeAxisUpperBound No(None)Maximum value for the range axis.
rangeAxisTickUnitNo(None)Range axis units between axis tick marks.
rangeAxisLabelAngleNo(None)Angle for the range axis label in degrees.
domainAxisLowerBoundNo(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.
domainAxisUpperBoundNo(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.
domainAxisTickUnitNo(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).
domainAxisLabelAngleNo(None)Only applies to XY plots. The angle for the domain axis label, in degrees. 
categoryLabelPositionNo(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
dateTickMarkPositionNo 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

ParameterRequiredDefaultDescription
pieSectionLabelNoShow 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%)
pieSectionExplodeNoNo exploded sectionsA 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.

ParameterRequiredDefaultDescription
attachmentNo(None)

The name and location where the chart image will be saved as an attachment. The user must be authorized 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.
  • name^attachmentName.png — the chart is saved as an attachment to the page name provided in the space indicated.
attachmentVersionNonew

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 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.
attachmentCommentNo(None) Comment used for a saved chart attachment.
thumbnailNofalse

 If true, the chart image attachment will be shown as a thumbnail (small, expandable) image.

tip/resting Created with Sketch.

Do more with Confluence

Create interesting and engaging charts for your Confluence pages with these top charts and diagrams apps on the Atlassian Marketplace.

Last modified on Mar 31, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.