General Actions:
Chart Macro
Last modified by Vincent Massol on 2013/03/11 09:39
 | Generates graphical charts from various data sources |
| Type | JAR |
| Developed by | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Enterprise, XWiki Enterprise Manager |
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:
{{chart source="xdom" type="<type>" params="<params>" title="<title>" height="<height>" width="<width>"/}}
Usage for "inline" data sources:
{{chart source="inline" type="<type>" params="<params>" title="<title>" height="<height>" width="<width>"}}
// Put your data table definition here.
{{/chart}}
// Put your data table definition here.
{{/chart}}
Parameters definition
| Name | Optional | Allowed values | Default value | Description |
|---|---|---|---|---|
| type | no | line, area, bar, pie, bar3D, 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 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 examples below). |
| 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 |
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:
(%id="table1"%)
|=|=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
|=|=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):
{{chart type="bar" params="document:<document_source_name>;table:table1;range:B2-D5;series:columns;" title="Chart Test" width="320" height="240"/}}
For our example with Main.Data, the syntax is:
{{chart type="bar" params="document:Main.Data;table:table1;range:B2-D5;series:columns;" title="Chart Test" width="320" height="240"/}}
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
{{chart type="pie" source="inline" params="range:B2-D5;series:columns;" title="Chart Test" width="320" height="240"}}
|=|=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}}
|=|=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"
{{chart type="xy_line_and_shape" params="range:B2-C19;dataset:timetable_xy;domain_axis_type:date;domain_axis_date_format:MMM-yyyy;date_format:yyyy-MM;time_period:month;range_axis_lower:100;range_axis_upper:190"}}
|=|=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}}
|=|=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"
{{chart type="xy_line3D" params="range:B2-C19;dataset:timetable_xy;domain_axis_type:date;domain_axis_date_format:MMM-yyyy;date_format:yyyy-MM;time_period:month;range_axis_lower:100;range_axis_upper:190"}}
|=|=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}}
|=|=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"
{{chart type="xy_step" params="range:B2-C19;dataset:timetable_xy;domain_axis_type:date;domain_axis_date_format:MMM-yyyy;date_format:yyyy-MM;time_period:month;range_axis_lower:100;range_axis_upper:190"}}
|=|=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}}
|=|=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:
3D Example
{{chart type='bar3D' source='inline' params='range:B2-B9;series:columns'}}
|=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}}
|=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:
Custom Colors Example
{{chart type="pie" source="inline" params="range:B2-D5;series:columns;colors:C3E3F7,1D9FF5,015891,012A45" title="Chart Test" width="320" height="240"}}
|=|=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}}
|=|=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:
