Search the Confluence 4.1.x Documentation:

Index
Downloads (PDF, HTML & XML formats)
Other versions

This documentation relates to Confluence 4.1.x
If you are using an earlier version, please view the previous versions of the Confluence documentation and select the relevant version.
Skip to end of metadata
Go to start of metadata

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.

Screenshots: A table of data in the Chart macro placeholder, and the resulting chart image.

On this page:

Using the Chart Macro

To add the Chart macro to a page:

  1. When editing the page, use autocomplete to add the Chart macro to the page. (Type '{' then begin typing the name of the macro, and choose it from the list of suggestions.)
  2. Enter your chart data as one or more tables in the body of the macro placeholder (see the screenshot above)
  3. Edit the macro and select a chart type using the Type parameter (see below).
  4. Make other parameter settings, in the Macro Browser, as described below.
  5. Click Preview to check that the chart appears as you expect.
  6. Finally, click Save to add the chart to your page.

Parameters

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 (beta)

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.
Height300The height of the chart in pixels.
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.

Colour Parameters

Colours are specified using hexadecimal notation or HTML colour names.

ParameterDefaultDescription
Background ColourWhiteBackground of the chart.
Border Colourno borderBorder 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.

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

Examples

Pie Chart

Parameters in Macro Browser

Data Table in Macro Placeholder

Rendered Chart

Typepie

Fish Type

2011

Herring

9,500

Salmon

2,900

Tuna

1,500

Chart TitleFish Sold 2011
Show Legendtrue
Content Orientationvertical
  
  
  

 

 

 

 

Bar Chart

Parameters in Macro BrowserData Table in Macro PlaceholderRendered Chart
Typebar

Fish Type

2010

2011

Herring

9,500

8,300

Salmon

2,900

4,200

Tuna

1,500

1,500

Chart TitleFish Sold
Show Legendtrue

 

 
  
  
  
  

 

3D Bar Chart

Parameters in Macro BrowserData Table in Macro PlaceholderRendered Chart
Typebar

 

2009

2010

2011

Revenue

12.4

31.8

41.1

Expense

43.6

41.8

31.1

Show in 3Dtrue
Opacity50
Show Legendtrue
  
  
  
  

Time Series Chart

Parameters in Macro BrowserData Tables in Macro PlaceholderRendered Chart
TypeTime 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 FormatMM/yyyy
Time PeriodMonth
Data Orientationvertical
Range Axis Lower Bound0
Show Legendtrue
  
  
  
  
  

 

XY Line Chart

Parameters in Macro BrowserData Table in Macro PlaceholderRendered Chart
TypexyLine

 

12

14

23

Revenue

41.1

31.8

12.4

Expense

31.1

41.8

43.6

Show Legendtrue

 

 

 

 

XY Area Chart

Parameters in Macro BrowserData Table in Macro PlaceholderRendered Chart
TypexyArea
 

12

14

23

Revenue

41.1

31.8

12.4

Expense

31.1

41.8

43.6

Show Legendtrue
  
  
  
  
  

 

Area Charts

Example 1
Parameters in Macro BrowserData Table in Macro PlaceholderRendered Chart
Typearea

Satisfaction

2009

2010

2011

Very satisfied

20

23

34

Satisfied

40

34

23

Dissatisfied

25

26

25

Very dissatisfied

15

17

18

Show Legendtrue
Width300
Height300
Opacity50

 

 

 

 

Example 2
Parameters in Macro Browser Data Table in Macro PlaceholderRendered Chart
Typearea

Satisfaction

2009

2010

2011

Very satisfied

12

23

31

Satisfied

1

34

36

Dissatisfied

4

6

22

Very dissatisfied

2

7

12

 

 

Show Legendtrue
Width300
Height300
Stacked Valuestrue

 

 

 

Related Topics

Working with Macros

Take me back to the Confluence User's Guide.

48 Comments

Hide/Show Comments

  1. Jan 09, 2009

    Don Gamble

    Is there a way to control the color of the text labels?

    1. Jan 09, 2009

      Bob Swift

      No, but it would be a valid improvement request.

  2. Mar 20, 2009

    Anonymous

    Hi,

    Is there a way to insert a numeric value in the body of a bar in the bar graph?

    Thanks

    1. Mar 29, 2009

      Azwandi Mohd Aris [Atlassian]

      I am sorry that this feature is not available in the macro. Perhaps, this feature request might be the one you after?

  3. Jul 16, 2009

    Anonymous

    Hi,

    Does this macro allow you to use an attachment (say a CSV file) as the data source?

    Thanks.

    1. Jul 16, 2009

      Sashidaran Jayaraman [Atlassian]

      Hi,

      This is possible with the use of another plugin called CSV Macro.

      Hope this helps.

      Cheers
      JSashi

  4. Jul 20, 2009

    Anonymous

    Hi,

    Can you chart off a "dynamictable" macro?

    Steve.

    1. Aug 10, 2009

      Zed Yap [Atlassian]

      Hi Steve,

      I am afraid that the feature requested is not available yet. Since, the dynamic macro is not part of this list:

      However, you might want to raise a feature request in JIRA:

      Hope that helps.
      Best rgds,
      Zed

  5. Jul 09, 2010

    Anonymous

    Can I change the line style on a line graph?  I'd like to make some dashes as opposed to solid.

    1. Aug 16, 2010

      Sashidaran Jayaraman [Atlassian]

      Hi,

      I am afraid that this is not currently possible. However, I have found a similar feature request Please add yourself as a watcher, vote for this feature and add your own comments to this feature request. For further details on how we include new features and improvements, you might want to read this page

      Cheers
      JSashi

  6. Oct 05, 2010

    Anonymous

    Is there a way to specify the colors of the wedges of a pie chart?

    we use green = on time, blue = late and red = very late. The standard colors work OK; however, if there are none in a particular category, the colors move around.

    This one works:

    But this one does not:

    Thanks for your assistance,

    1. Jan 21, 2011

      Anonymous

      Have you tried adding a wedge with a value of 0 as a place holder to keep the color assignments the same?

  7. Sep 22, 2011

    Anonymous

    Is there any way to make multiple charts from one table. ie use columns 1,2 and 3 of a table for one graph and then 1,2 and 5 for some other graph? This is pretty much essential if the table's are generated by sql queries (and the SQL macro) because it becomes very inefficient to run 5 similar queries for 5 graphs.
    Thanks

    Iain

    1. Feb 28, 2011

      Bob Swift

      Put the sql query on a separate page surrounded by the cache macro. Include the sql page for each chart using the include macro. Use the columns parameter in the chart macro for the column selection.

  8. Dec 08, 2010

    Anonymous

    Is it possible to add a vertical line to mark the median value on the x axis? For example, when charting a count of items by age, to indicate the median age. Thanks

  9. Jan 05, 2011

    shlomi Podgorovich

    Hi,

    Is there a way to view the data labels ( like in excel) in a graph?

    I am not referring to the label name but to the value of the graph column.

    Thanks,

  10. Feb 05, 2011

    Peter Alfvin

    I'd like to create a line chart where some of the lines don't extend all the way to the right, as used in an "actual vs. plan" chart.  However, if I leave the corresponding cells of the input table blank, they are treated as zeros, resulting in the line dropping to the x-axis at the point of the nulls and continuing on from there.

    Am I missing something?  Is this a feature request matter?  Has a request already been submitted?

    Thanks in advance for any info.

    Pete Alfvin

    P.S. I tried to include an image to show what I was looking for, but it wouldn't let me drag/drop a .jpg file from my desktop through Insert Image.

    1. Dec 21, 2011

      Anonymous

      Same thing happened to me and I separated the data into two tables to work around the issue.

      Instead of:

      {chart}
|| Date || Planned || Actual ||
| Jan 1 | 100 | 100 |
| Jan 2 | 75 | 75 |
| Jan 3 | 50 |    |
| Jan 4 | 25 |    |
| Jan 5 | 0  |    |
{chart}

      Do this:

      {chart}
|| Date || Planned ||
| Jan 1 | 100 |
| Jan 2 | 75  |
| Jan 3 | 50  |
| Jan 4 | 25  |
| Jan 5 | 0   |


|| Date || Actual ||
| Jan 1 | 100 |
| Jan 2 | 75  |
{chart}

       

      Each day you add a value to actual, you create the row with the date and actual value.

  11. Feb 28, 2011

    Anonymous

    If I have an SQL plugin returning multiple tables, is there a way to have multiple charts based on that content? Splitting the SQL isn't an easy option since the data is built dynamically from relatively complex SQL.

    1. Feb 28, 2011

      Bob Swift

      Almost (sad). The tables parameter is meant for things like this. It is a way to specify explicitly what tables in the body are to be used for a chart. Macros like sql, table-plus, csv, excel all have an id parameter to explicitly put an id on a table. Unfortunately, the sql macro does not auto-increment the id for multiple result set tables. I have created SQL-109 to cover this case.

      1. Feb 28, 2011

        Anonymous

        Thanks! So the multiple chart macros don't need to wrap around the SQL macro if the tables are numbered are somewhere in the page body? Have I got that right?

        1. Feb 28, 2011

          Bob Swift

          I wasn't as complete as I needed to be. Any tables the chart macro needs to access MUST be in the body of the chart macro. In your case you probably need to use this technique as well once the issue gets fixed.

  12. Mar 22, 2011

    Okan A.

    Is there a way to drill down on charts? In other words, can I make the data points on a chart dynamic?

  13. Mar 22, 2011

    Anonymous

    Is there a way to limit the width of the chart to a certain number of pixels irrespective of the data domain ?

    ^|____,____100

    and for same width in pixels

    |____,_____20

  14. Apr 01, 2011

    Anonymous

    How to show DateTickMarks in "xyline" charts?

    How to use domainAxisTickUnit in "line" chart? This setting is neglected.

    How to change order of functions on "xyline" and "line" charts? Function drawn later overlaps function drawn earlier.

    Thanks

  15. Jun 29, 2011

    Anonymous

    Is there any possible way to develop a time series chart but instead of a line, it has the area shaded in??

  16. Jul 06, 2011

    Anonymous

    Is it possible to have a hyperlink in the chart? So when i press my line I get forwarded to another page?

    1. Jul 14, 2011

      Anonymous

      Have you figured out how to get the drill through working?

      1. Jul 14, 2011

        Bob Swift

        I have used imagemap macro in the past for things like this.

  17. Jul 28, 2011

    Anonymous

    Can i have a chart with x-axis = day and y-axis = hour of the day?

  18. Jul 28, 2011

    Anonymous

    Is the Gantt option of the chart macro still in beta? I am having trouble using it because the example code is not working for me

    Thanks!

  19. Aug 09, 2011

    Barri Jansen

    Why isn't it possible to set the stacked=true parameter on the XY-plots charts.

    I've a timeseries data-range with 1 year of data, for each day a value. Plotting this in an Area chart the x-axis losses precision. With the xyArea chart I can set the domainAxisTickUnit=1M parameter. Which result in a nice x-axis showing each month!

    The data really makes more sense showing stacked. So I've to use the area chart, now I'm missing the x-axis :-(

  20. Aug 09, 2011

    Anonymous

    Hi - is there a list of colours that can be used?

    Thanks and kind regards from Switzerland

  21. Aug 25, 2011

    Kenneth Houmark

    How do i turn a table (a SQL result) like this into a bar chart where y axis is Hours and the x-axis has a bar for each pair of User,Customer:

    User

    Hours

    Customer

    Paul

    30

    C1

    Paul

    2

    C2

    Lola

    3

    C3

    Using type = bar and dataOrientation=vertical does not work. Even tried with yLabel=Hours
    Been struggeling for hours! :D Would really help my company.

    1. Sep 23, 2011

      Mike Frohme

      Hi Kenneth,

      This may not be the most helpful answer, but combining the User and Customer data into a single column with type bar" and orientation "vertical" accomplishes what you want, e.g.

      {chart:type=bar|dataOrientation=vertical|displayData=true}

      User+CustHours
      Paul (C1)30
      Paul (C2)2
      Lola (C3)3

  22. Aug 31, 2011

    Anonymous

    I'd like to mark today's date in a gant chart with a vertical line, is that possible?

  23. Sep 07, 2011

    Anonymous

    Dear All

    Is it possible to assing rangeAxisLowerBound to the minimum value automatically in dataset. I only see manual forcing of lower and uppper bound something like  |rangeAxisLowerBound=0I.

    Thank you very much.

     

  24. Sep 23, 2011

    Anonymous

    I liked the old version of this page much better. In the new version it is not clear how the parameters are named.

    For example, the parameter borderColor is now called "Border Colour". This isn't very helpful (sad)

    1. Sep 23, 2011

      Mike Frohme

      I agree completely - some names are directly related to what's in the description - e.g. dateFormat = "Date Format" but parameter rangeaxisupperbound is not intuitively obvious from "Range Maximum Value"  though the Domain axis appears to be better.

      I actually downloaded and scrounged the source to get to that ... grrr.

      1. Oct 04, 2011

        Paul Watson [Atlassian Technical Writer]

        Hi Mike,

        Thanks for your comment. By way of explanation, the parameter descriptions on this page match those in the Macro Browser, which is what you use to configure macros in Confluence 4.0.

        I assume that you are using a version of Confluence earlier the 4.0. I think you will find the information you require if you refer to the version of the documentation that is relevant for your version of Confluence. Links are available at the top left of this page.

        I hope this helps,

        regards

        Paul

  25. Oct 04, 2011

    Brooke Gravitt

    Wouldn't it be nice to include a code block with each example? You know, if only Confluence allowed you to do something like that...

     


    Pie Chart Example:

    Chart Code

  26. Oct 05, 2011

    Anonymous

    Is there a reason why there is no selection in the parameters for the type of chart? Any time I make an edit to my bar chart, it reverts back to a pie chart and I have to start over again. I cannot seem to even open the wiki markup anymore to make the adjustments. 

  27. Oct 15, 2011

    Anonymous

    Regarding the chart type bar parameters: Is there any way of displaying the numeric amount values over each specific bar?

  28. Nov 17, 2011

    nicolas frank

    The plugin is not properly working with confluence 4.x : you can't chose the chart type through the ui... so you can only create pie graphs (and as you can't access the wiki markup anymore... so no way to do this manually...)... we are blocked by this issue... I raised a bug on the plugin JIRA site, please fix this quick !!!

  29. Dec 11, 2011

    Anonymous

    The following parameters are documented wrong in the table above and they really should be:

     

    Range Axis Lower BoundnoneRange axis minimum value (ie y axis minimum)
    Range Axis Upper Bound
    		noneRange axis maximum value (ie y axis maximum)
    Display 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.
      • true — the data are displayed after the chart (same as the after parameter)

    1. Dec 12, 2011

      Paul Watson [Atlassian Technical Writer]

      Thanks for your comment!

      You are describing an older version of Confluence, while this page describes the Chart Macro in Confluence 4.0.x.

      regards, Paul

  30. Feb 08, 2012

    lecaros

    I'd like to display stacked values in a bar chart considering it's percentage in y axis. Let's say we have following table

    IngredientsSand1Sand2
    Bacon4516
    Green stuff58

    It should display 2 bars, one for Sand1 and one for Sand2, both bars should have same size and vary colors according to percentage. Say, Bacon-color in Sand1 should cover 90% of the bar, Green stuff color should use the 10%... same applies for Sand2's bar, 67% for bacon 33% for green stuff.

    Is this currently supported in chart macro?

     

    thanks in advance!

  31. Feb 09, 2012

    Anonymous

    In confluence 4.1 how to create different chart types using Jira filters (jiraissues) and use them in WIki?