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.
Macro contents
Rendered chart
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.
|
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 |
| 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.
|
Image format | png | The image format to be used for the chart.
|
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 |
|
Time Series | false |
|
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 |
|
Color Parameters
Colors are specified using hexadecimal notation or HTML color names.
Parameter | Default | Description |
---|---|---|
Background Color | White | Background of the chart. |
Border Color | no border | Border 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.
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.
|
Date Tick Mark Position | start | Placement of the date tick mark.
|
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:
Example 1: "%0% = %1%" 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 Plugin to 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 authorized to add attachments to the page specified.
|
Attachment Version | new | Defines the the versioning mechanism for saved charts.
|
Attachment Comment | none | Comment used for a saved chart attachment. |
Thumbnail | false |
|
Examples
Pie Chart
Parameters in Macro Browser | Data Table in Macro Placeholder | Rendered Chart | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Type | pie |
| ![]() | ||||||||
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 |
| ![]() | ||||||||||||
Chart Title | Fish Sold | ||||||||||||||
Show Legend | true | ||||||||||||||
3D Bar Chart
Parameters in Macro Browser | Data Table in Macro Placeholder | Rendered Chart | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Type | bar |
| ![]() | ||||||||||||
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 |
|
| ![]() | ||||||||||||||||||||||||||||||||||||||||||||||||||||
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 |
| ![]() | ||||||||||||
Show Legend | true | ||||||||||||||
XY Area Chart
Parameters in Macro Browser | Data Table in Macro Placeholder | Rendered Chart | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Type | xyArea |
| ![]() | ||||||||||||
Show Legend | true | ||||||||||||||
Area Charts
Example 1
Parameters in Macro Browser | Data Table in Macro Placeholder | Rendered Chart | |||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Type | area |
| ![]() | ||||||||||||||||||||
Show Legend | true | ||||||||||||||||||||||
Width | 300 | ||||||||||||||||||||||
Height | 300 | ||||||||||||||||||||||
Opacity | 50 | ||||||||||||||||||||||
Example 2
Parameters in Macro Browser | Data Table in Macro Placeholder | Rendered Chart | |||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Type | area |
| ![]() | ||||||||||||||||||||
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 |
| ![]() | ||||||||||||||||||||||||||||||||
Width | 300 | ||||||||||||||||||||||||||||||||||
Height | 200 | ||||||||||||||||||||||||||||||||||
Columns | ,,1,2,3,4 | ||||||||||||||||||||||||||||||||||
Date format | MM/dd/yyyy | ||||||||||||||||||||||||||||||||||
Code examples
Wiki markup is useful when you need 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.
This macro recognizes 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 Available values:
|
orientation | No | vertical | The display orientation. Applies to area, bar and line charts. Available values:
|
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 |
| 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:
|
imageFormat | No | png | The image format to be used for the chart. Available values:
|
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:
|
timeSeries | No | false | If ' |
dateFormat | No | 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 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: |
language | No | (None) | Use in combination with the 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:
|
Chart color parameters
Colors are specified using hexadecimal notation or HTML color names.
Parameter | Required | Default | Description |
---|---|---|---|
bgColor | No | White | Background color of the chart. |
borderColor | No | No border | Color of the border around the chart. |
colors | No | 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.
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:
|
dateTickMarkPosition | No | start | Placement of the date tick mark. Available values:
|
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:
Example 1: To display something like 'Independent = 20':
|
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 authorized to add attachments to the page specified. Available syntax for this parameter:
|
attachmentVersion | No | new | Defines the the versioning mechanism for saved charts. Available values:
|
attachmentComment | No | (None) | Comment used for a saved chart attachment. |
thumbnail | No | false | If |
Wiki markup example
Wiki markup is only supported in the legacy editor.
Below is a simple example of a pie chart.
{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}