The XChart module is used to build charts and display them in the form of an image in a document. This module uses the Java open source framework XChart: https://knowm.org/open-source/xchart/.
It is based on XChart version 3.5.2.
The purpose of this documentation is not to detail all the properties used by XChart to create a chart but only how to describe these properties within the scope of use via the APE.
It is therefore necessary to familiarise yourself with the concepts introduced by XChart. To do this, see the following pages:
- https://github.com/knowm/XChart
- https://knowm.org/open-source/xchart/xchart-example-code/
- https://knowm.org/javadocs/xchart/index.html
A set of APE template examples are provided in the apesamples examples database. These examples are the migration of Java class examples provided by the XChart framework (https://github.com/knowm/XChart/tree/develop/xchart-demo).
The XChart module supports the seven main types of chart offered by the XChart framework:
Chart type |
Styles class |
Series class |
Type of Java data authorized |
Default series render style |
XYChart |
XYStyler |
XYSeries |
Number, Date |
Line |
CategoryChart |
CategoryStyler |
CategorySeries |
Number, Date, String |
Bar |
PieChart |
PieStyler |
PieSeries |
String |
Pie |
BubbleChart |
BubbleStyler |
BubbleSeries |
Number, Date |
Round |
DialChart |
DialStyler |
DialSeries |
double |
Round |
RadarChart |
RadarStyler |
RadarSeries |
double[] |
Round |
OHLCChart |
OHLCStyler |
OHLCSeries |
OHLCwith Date |
Candle |
The XChart module is used in an APE template with the aid of an inclusion direction to insert at the start of the template:
<#import "/lib_xchart.ftl" as xchartModule/>
NB: The "xchartModule" namespace name is provided as an example and can be replaced by a name of your choosing (in accordance with Apache Freemarker namespaces syntax).
This module offers seven Freemarker macros and each one can represent one of the five types of XChart charts:
- <@xchartModule.xyChart /> : Represents an XYChart,
- <@xchartModule.categoryChart /> : Represents a CategoryChart,
- <@xchartModule.pieChart /> : Represents a PieChart,
- <@xchartModule.bubbleChart /> : Represents a BubbleChart,
- <@xchartModule.dialChart /> : Represents a DialChart,
- <@xchartModule.radarChart /> : Represents a RadarChart,
- <@xchartModule.ohlcChart /> : Represents an OHLCChart,
NB: These macros have no content (no end tags). A chart description is created by entering its parameters.
These seven macros have a set of common parameters, namely:
- Required parameters:
| Parameter type | Parameter name | Description |
Number |
width |
Width in pixels of the imagerepresenting the chart. |
Number |
height |
Height in pixels of the image representing the chart. |
Hash sequence |
series |
Sequence of Hash objects describing the chart data. Each data series is represented by a Hash object. The type of a series (the Hash object) depends on the type of chart to represent. The Hash object contains a set of properties which represent:
|
String / Hash |
drawformat |
Information on the image format. If the type is "String", the value must be one of the following:
If the type is "Hash", the quality can be specified for PNG and JPEG image formats using the following keys:
|
- Optional parameters:
| Parameter type | Parameter name | Description |
String |
title |
Chart type. |
Hash |
style |
Hash object grouping a chart's style properties. These properties are grouped into several sets to represent the Java classes of the Chart Styler framework, AxesChartStyler, DialStyler, PieStyler, RadarStyler, BubbleStyler, CategoryStyler, OHLCStyler, XYStyler. |
For example:
<#-- Just one seriefor Dial Graph -->
<#assigndialSeries= [{"name": "Fill rate", "value": 0.9381}] />
<@xchartModule.dialCharttitle="Storage workload" width=500 height=400 series=dialSeriesdrawformat="svg"/>