Chart Macro
 | Macro for displaying charts |
| Type | JAR |
| Category | |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard |
Table of contents
Description
Usage
Currently chart macro supports two types of data sources. Usage of the macro slightly differs from "xdom" mode to "inline" mode:
Usage for "xdom" data sources:
Usage for "inline" data sources:
// Put your data table definition here using the current page's syntax
{{/chart}}
Parameters definition
| Name | Optional | Allowed values | Default value | Description |
|---|---|---|---|---|
| type | no | line, area, bar, stackedbar, bar3D, stackedbar3D, pie, line3D, xy_area, xy_line_and_shape, xy_line3D and xy_step | none | Type of chart to be generated. |
| source | yes | xdom or inline | inline if the macro has content (the content needs to be written using the page's syntax) or xdom otherwise | Type of the data source which provides input for charting. |
| params | yes | string | none | Additional parameters for the data source. This string contains a list of parameter name to value mappings. Available parameter names and values depend on the data source being used (refer to the examples below). Note that when specifying a range (as in range:B2-D5) you can use the #.# (dot) character to specify the maximum column or line. For example range:B2-D. means till the max line and range:B2-.. means last column and last line. |
| title | yes | string | none | A title string to be used when rendering the chart |
| width | yes | string | 400 | Width of the chart image in pixels |
| height | yes | string | 300 | Height of the chart image in pixels |
| colors | yes | string | none | List of custom colors to use, specified in hexadecimal. Example: FF0000,00FF00,0000FF |
Generic Parameters
| Parameter name | Default value | Description |
|---|---|---|
| backgroundColor | Grey background | Background color of the non-chart area, specified using an hexadecimal notation, e.g. FFAACC (first 2 letters are for Red, following 2 are for Green and last 2 are for Blue). |
| plotBackgroundColor | White | Background color of the plot area, specified using an hexadecimal notation (see backgroundColor). |
| plotBorderColor | Black | Color of the plot border, specified using an hexadecimal notation (see backgroundColor). |
| borderColor | Black | Color of the outer graph border, specified using an hexadecimal notation (see backgroundColor). |
| legendBackgroundColor | White | Background color of the legend box, specified using an hexadecimal notation (see backgroundColor). |
| plotBorderVisible | true | Whether the border for the plot area is visible or not. Valid values are true and false. |
| legendVisible | true | Whether the legend is displayed or not. Valid values are true and false. |
Pie Chart Parameters
| Parameter name | Default value | Description |
|---|---|---|
| pie_label_format | {0} | The format of the label for pie segments. Use {0} where the pie section key should be inserted, {1} for the absolute section value and {2} for the percent amount of the pie section, e.g. {0} = {1} ({2}) will display as "apple = 120 (5%)". |
Examples
Example for an "xdom" data source Bar chart
An "xdom" data source can be used when you need to draw charts from data tables located anywhere in the wiki. For an example, let's say xwiki:Main.Data wiki page contains the following data table definition:
|=|=X|=Y|=Z
|Q1|1.2|3.4|1.3
|Q2|4.5|3.4|2.3
|Q3|1.2|4.5|9.0
|Q4|3.4|1.2|1.2
Then you can draw a chart from this data table with following syntax (from any wiki page):
For our example with Main.Data, the syntax is:
NOTE: As you can see here, the "params" string is used to clearly define input data source:
- Wiki page: "document:Main.Data;"
- Name of the data table: "table:table1;" (the table must have an id)
- Data range: "range:B2-D5;" (just like you'd select a data range on an excel sheet)
- Orientation: "series:columns;" (defines the x and y axes)
Result:
Example for an "inline" data source Pie chart
Example for a page using XWiki Syntax 2.0 or XWiki Syntax 2.1 (the table syntax is in XWiki Syntax 2.0 or XWiki Syntax 2.1).
|=|=X|=Y|=Z
|Q1|1.2|3.4|1.3
|Q2|4.5|3.4|2.3
|Q3|1.2|4.5|9.0
|Q4|3.4|1.2|1.2
{{/chart}}
Result:
See also the Syntax Distribution Chart Snippet for another example.
Example of a Time Series chart
Using "xy_line_and_shape"
Example for a page using XWiki Syntax 2.0 or XWiki Syntax 2.1 (the table syntax is in XWiki Syntax 2.0 or XWiki Syntax 2.1).
|=|=Series1|=Series2
|2001-2|181.8|129.6
|2001-3|167.3|123.2
|2001-4|153.8|117.2
|2001-5|167.6|124.1
|2001-6|158.8|122.6
|2001-7|148.3|119.2
|2001-8|153.9|116.5
|2001-9|142.7|112.7
|2001-10|123.2|101.5
|2001-11|131.8|106.1
|2001-12|139.6|110.3
|2002-1|142.9|111.7
|2002-2|138.7|111.0
|2002-3|137.3|109.6
|2002-4|143.9|113.2
|2002-5|139.8|111.6
|2002-6|137.0|108.8
|2002-7|132.8|101.6
{{/chart}}
Result:
Using "xy_line3D"
Example for a page using XWiki Syntax 2.0 or XWiki Syntax 2.1 (the table syntax is in XWiki Syntax 2.0 or XWiki Syntax 2.1).
|=|=Series1|=Series2
|2001-2|181.8|129.6
|2001-3|167.3|123.2
|2001-4|153.8|117.2
|2001-5|167.6|124.1
|2001-6|158.8|122.6
|2001-7|148.3|119.2
|2001-8|153.9|116.5
|2001-9|142.7|112.7
|2001-10|123.2|101.5
|2001-11|131.8|106.1
|2001-12|139.6|110.3
|2002-1|142.9|111.7
|2002-2|138.7|111.0
|2002-3|137.3|109.6
|2002-4|143.9|113.2
|2002-5|139.8|111.6
|2002-6|137.0|108.8
|2002-7|132.8|101.6
{{/chart}}
Result:
Using "xy_step"
Example for a page using XWiki Syntax 2.0 or XWiki Syntax 2.1 (the table syntax is in XWiki Syntax 2.0 or XWiki Syntax 2.1).
|=|=Series1|=Series2
|2001-2|181.8|129.6
|2001-3|167.3|123.2
|2001-4|153.8|117.2
|2001-5|167.6|124.1
|2001-6|158.8|122.6
|2001-7|148.3|119.2
|2001-8|153.9|116.5
|2001-9|142.7|112.7
|2001-10|123.2|101.5
|2001-11|131.8|106.1
|2001-12|139.6|110.3
|2002-1|142.9|111.7
|2002-2|138.7|111.0
|2002-3|137.3|109.6
|2002-4|143.9|113.2
|2002-5|139.8|111.6
|2002-6|137.0|108.8
|2002-7|132.8|101.6
{{/chart}}
Result:
Stacked Bar Example
Result:
3D Examples
Example for a page using XWiki Syntax 2.0 or XWiki Syntax 2.1 (the table syntax is in XWiki Syntax 2.0 or XWiki Syntax 2.1).
|=Date|=Value
|2012-02-21|1.97
|2012-02-26|2.96
|2012-03-04|3.93
|2012-03-11|4.84
|2012-03-18|5.83
|2012-03-25|4.5
|2012-04-01|3.85
|2012-04-08|4.87
{{/chart}}
Result:
Result:
Custom Colors Example
Example for a page using XWiki Syntax 2.0 or XWiki Syntax 2.1 (the table syntax is in XWiki Syntax 2.0 or XWiki Syntax 2.1).
|=|=X|=Y|=Z
|Q1|1.2|3.4|1.3
|Q2|4.5|3.4|2.3
|Q3|1.2|4.5|9.0
|Q4|3.4|1.2|1.2
{{/chart}}
Result:
Line chart without shapes for data points
Example for a page using XWiki Syntax 2.0 or XWiki Syntax 2.1 (the table syntax is in XWiki Syntax 2.0 or XWiki Syntax 2.1).
The line chart type supports two additional parameters to hide the shapes used to display the data points or to hide the interpolation lines that connect the data points.
|=Date|=Warning|=Critical|=% Used
|1|90|80|85
|20|90|80|93
{{/chart}}
Pie chart with white background
Pie chart with no legend displayed, no border, no title and white background.
Example for a page using XWiki Syntax 2.0 or XWiki Syntax 2.1 (the table syntax is in XWiki Syntax 2.0 or XWiki Syntax 2.1).
|=|=X|=Y|=Z
|Q1|1.2|3.4|1.3
|Q2|4.5|3.4|2.3
|Q3|1.2|4.5|9.0
|Q4|3.4|1.2|1.2
{{/chart}}
Advanced Customization
For advanced customizations, you can implement the org.xwiki.chart.ChartCustomizer component role to have access to the org.jfree.chart.JFreeChart object, allowing you to fully customize the generated charts.
This can be implemented either as a component in Java or using wiki components.
The ChartCustomizer interface:
public interface ChartCustomizer
{
/**
* @param jFreeChart the JFree Chart instance representing the graph, on which customizations can be performed
* @param parameters the parameters passed to the Chart generator and controlling its aspect (e.g. the Chart Macro
* allows user to pass those parameters as a string, for example
* {@code range:B2-D5;series:columns;colors:C3E3F7,1D9FF5,015891,012A45}
*/
void customize(JFreeChart jFreeChart, Map<String, String> parameters);
}
Example implementation in Java:
* Customize visiblity of items on the chart.
*
* @version $Id: 35065820fcab9859b41f18a2526365756a882d7d $
* @since 7.4.3, 8.0RC1
*/
@Component
@Named("visibility")
@Singleton
public class VisibilityChartCustomizer implements ChartCustomizer
{
/**
* Whether the plot border is visible or not.
*/
private static final String PLOT_BORDER_VISIBLE = "plotBorderVisible";
/**
* Whether the legend is visible or not.
*/
private static final String LEGEND_VISIBLE = "legendVisible";
@Override
public void customize(JFreeChart jfchart, Map<String, String> parameters)
{
if (parameters.get(PLOT_BORDER_VISIBLE) != null) {
jfchart.getPlot().setOutlineVisible(Boolean.parseBoolean(parameters.get(PLOT_BORDER_VISIBLE)));
}
if (parameters.get(LEGEND_VISIBLE) != null && !Boolean.parseBoolean(parameters.get(LEGEND_VISIBLE))) {
jfchart.removeLegend();
}
}
}
Prerequisites & Installation Instructions
We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).
You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.
Dependencies
Dependencies for this extension (org.xwiki.platform:xwiki-platform-chart-macro 16.10.1):
- commons-io:commons-io 2.17.0
- org.xwiki.platform:xwiki-platform-chart-renderer 16.10.1
- org.xwiki.platform:xwiki-platform-bridge 16.10.1
- org.xwiki.platform:xwiki-platform-display-api 16.10.1
- org.xwiki.platform:xwiki-platform-security-authorization-api 16.10.1
- org.xwiki.rendering:xwiki-rendering-api 16.10.1
- org.xwiki.rendering:xwiki-rendering-transformation-macro 16.10.1
