Supported charts
Pentaho Reporting relies on JFreeChart, an open source Java chart library, for charting visualization within reports. From within Report Designer, many chart types are supported. In the chart editor, two areas of properties appear when editing a chart. The first area of properties is related to chart rendering, and the second tabbed area of properties is related to the data that populates a chart. Following is the screenshot of the chart editor within Pentaho Report Designer:
All chart types receive their data from three general types of datasets. The first type is known as a Category Dataset , where the dataset series and values are grouped by categories. A series is like a sub-group. If the exact category and series appear, the chart will sum the values into a single result. The following table is a simple example of a category dataset:
Category |
Series |
Sale Price |
Store 1 Sales |
Cash |
$14 |
Store 1 Sales |
Credit |
$12 |
Store 2 Sales |
Cash |
$100 |
Store 2 Sales |
Credit |
$120 |
Pentaho Reporting builds a Category Dataset using the CategorySetDataCollector. Also available is the PivotCategorySetCollector, which pivots the category and series data. Collector classes implement Pentaho Reporting’s Function API.
The second type of dataset is known as an XY Series Dataset, which is a two dimensional group of values that may be plotted in various forms. In this dataset, the series may be used to draw different lines, and so on. Here is a simple example of an XY series dataset :
Series |
Cost of Goods (X) |
Sale Price (Y) |
Cash |
10 |
14 |
Credit |
11 |
12 |
Cash |
92 |
100 |
Credit |
105 |
120 |
Note that X is often referred to as the domain, and Y is referred to as the range. Pentaho Reporting builds an XY Series Dataset using the XYSeriesCollector. The XYZSeriesCollector also exists for three dimensional data.
The third type of dataset is known as a Time Series Dataset , which is a two dimensional group of values that are plotted based on a time and date. The Time Series Dataset is more like an XY Series than a Category Dataset, as the time scale is displayed in a linear fashion with appropriate distances between the different time references.
Time |
Series |
Sale Price |
May 05, 2009 11:05pm |
Cash |
$14 |
June 07, 2009 12:42pm |
Credit |
$12 |
June 14, 2009 4:20pm |
Cash |
$100 |
June 01, 2009 1:22pm |
Credit |
$120 |
Pentaho Reporting builds a Time Series Dataset using the TimeSeriesCollector.
Common chart rendering properties
Most charts share a common set of properties. The following properties are common across most charts. Any exceptions are mentioned as part of the specific chart type.
Required Property Group |
|
Property name |
Description |
name |
The name of the chart object within the report. This is not displayed during rendering, but must be unique in the report. A default name is generated for each chart added to the report. |
data-source |
The dataset name for the chart, which is automatically populated with the name of the dataset in the Primary DataSource panel of the chart editor. |
no-data-message |
The message to display if no data is available to render the chart. |
Title Property Group |
|
Property name |
Description |
chart-title |
The title of the chart, which is rendered in the report. |
chart-title-field |
A field representing the chart title. |
title-font |
The chart title’s font family, size, and style. |
Options Property Group |
|
Property name |
Description |
horizontal |
If set to True, the chart’s X and Y axis are rotated horizontally. The default value is set to False. |
series-colors |
The color in which to render each series. The default for the first three series colors are red, blue, and green. |
General Property Group |
|
Property name |
Description |
3-D |
If set to True, renders the chart in a 3D perspective. The default value is set to False. |
anti-alias |
If set to True, renders chart fonts as anti-aliased. The default value is set to True. |
bg-color |
Sets the background around the chart to the specified color. If not set, defaults to gray. |
bg-image |
Sets the background of the chart area to the specified image. If not set, the background of the chart area defaults to white. The chart area is the area within the axes of the chart. Supported image types include PNG, JPG, and GIF file formats. |
show-border |
If set to True, displays a border around the chart. The default value is set to True. |
border-color |
Sets the border to the specified color. If not set, defaults to black. |
plot-border |
If set to False, clears the default rendering value of the chart border. |
plot-bg-color |
Sets the plot background color to the specified color. If not set, defaults to white. |
plot-fg-alpha |
Sets the alpha value of the plot foreground colors relative to the plot background. The default value is set to 1.0. |
plot-bg-alpha |
Sets the alpha value of the plot background color relative to the chart background color. The default value is set to 1.0. |
Legend Property Group |
|
Property name |
Description |
show-legend |
If set to True, displays the legend for the chart. The default value is set to False. |
location |
The location of the legend in relation to the chart, which may be set to top, bottom, left, or right. The default location is bottom. |
legend-border |
If set to True, renders a border around the legend. The default value is set to True. |
legend-font |
The type of Java font to render the legend labels in. |
legend-bg-color |
Sets the legend background color. If not set, defaults to white. |
legend-font-color |
Sets the legend font color. If not set, defaults to black. |
Advanced Property Group |
|
Property name |
Description |
dependencyLevel |
The dependency level field informs the reporting engine what order the chart should be executed in relation to other items in the report. This is useful if you are using special functions that may need to execute prior to generating the chart. The default value is set to 0. Negative values execute before 0, and positive values execute after 0. |
Common category series rendering properties
The following properties appear in charts that render category information:
Options Property Group |
|
Property name |
Description |
stacked |
If set to True, the series values will appear layered on top of one another instead of being displayed relative to one another. |
stacked-percent |
If set to True, determines the percentages of each series, and renders the bar height based on those percentages. The property stacked must be set to True for this property to have an effect. |
General Property Group |
|
Property name |
Description |
gridlines |
If set to True, displays category grid lines. This value is set to True by default. |
X-Axis Property Group |
|
Property name |
Description |
label-rotation |
If set, adjusts the inline item label rotation value. The value should be specified in degrees. If not specified, labels are rendered horizontally. You must have show-labels set to true for this value to be relevant. |
date-format |
If the item value is a date, a Java date format string may be provided to format the date appropriately. Please see Java’s SimpleDateFormat JavaDoc for formatting details. |
numeric-format |
If the item value is a decimal number, a Java decimal format string may be provided to format the number appropriately. Please see Java’s DecimalFormat JavaDoc for formatting details. |
text-format |
The label format used for displaying category items within the chart. This property is required if you would like to display the category item values. The following parameters may be defined in the format string to access details of the item:
To display just the item value, set the format string to “{2}”. |
x-axis-title |
If set, displays a label describing the category axis. |
show-labels |
If set to true, displays x-axis labels in the chart. |
x-axis-label-width |
Sets the maximum category label width ratio, which determines the maximum length each category label should render in. This might be useful if you have really long category names. |
x-axis-label-rotation |
If set, adjusts the category item label rotation value. The value should be specified in degrees. If not specified, labels are rendered horizontally. |
x-font |
The font to render the category axis title and labels in. |
Y-Axis Property Group |
|
Property name |
Description |
y-axis-title |
If set, displays a label along the value axis of the chart. |
label-rotation |
If set, determines the upward angle position of the label, where the value passed into JFreeChart is the mathematical pie over the value. Unfortunately, this property is not very flexible and you may find it difficult to use. |
y-tick-interval |
The numeric interval value to separate range ticks in the chart. |
y-font |
The font to render the range axis title in. |
y-sticky-0 |
If the range includes zero in the axis, making it sticky will force truncation of the axis to zero if set to True. The default value of this property is True. |
y-incl-0 |
If set to True, the range axis will force zero to be included in the axis. |
y-min |
The minimum value to render in the range axis. |
y-max |
The maximum value to render in the range axis. |
y-tick-font |
The font to render the range tick value in. |
y-tick-fmt-str |
The DecimalFormat string to render the numeric range tick value. |
enable-log-axis |
If set to true, displays the y-axis as a logarithmic scale. |
log-format |
If set to true, will present the logarithmic scale in a human readable view. |