Including Charts and Graphics in Pentaho Reports (Part 1)

Exclusive offer: get 50% off this eBook here
Pentaho Reporting 3.5 for Java Developers

Pentaho Reporting 3.5 for Java Developers — Save 50%

Create advanced reports, including cross tabs, sub-reports, and charts that connect to practically any data source using open source Pentaho Reporting.

$26.99    $13.50
by Will Gorman | September 2009 | Java Open Source

In this two-part article by Will Gorman, you'll learn how to incorporate charts and graphics into Pentaho Reports. You'll learn about the different types of charts supported, and how to configure them in Pentaho Report Designer. You'll also learn how to populate a chart with various types of data.

In addition to learning all about charts, this article also covers the various methods for including visual information in your report, including embedding images and Java graphics in your report.

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:

Pentaho Reporting 3.5 for Java Developers

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:

  • {0}: To access the Series Name detail of an item
  • {1}: To access the Category detail of an item
  • {2}: To access the Item value details of an 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.

Pentaho Reporting 3.5 for Java Developers Create advanced reports, including cross tabs, sub-reports, and charts that connect to practically any data source using open source Pentaho Reporting.
Published: September 2009
eBook Price: $26.99
Book Price: $44.99
See more
Select your format and quantity:

Common XY series rendering properties

The following properties appear in charts that render XY series information.

X-Axis Property Group

Property name

Description

x-incl-0

If set to True, the domain axis will force zero to be included in the axis. The default value of this property is True.

x-min

The maximum value to render in the domain axis.

x-max

The minimum value to render in the domain axis.

x-sticky-0

If the domain 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.

x-tick-font

The font in which to render the domain tick value.

x-tick-fmt-str

The DecimalFormat string to render the numeric domain tick value.

x-title

The title to display on the domain axis.

x-font

The font in which to render the domain axis title.

x-vtick-label

If True, renders the domain tick labels vertically. This value defaults to False.

x-tick-interval

The numeric interval value to separate x-axis ticks in the chart.

x-tick-time-period

If rendering a time series dataset, this property is the time period to display in the x-axis.

Y-Axis Property Group

Property name

Description

y-incl-0

If set to True, the range axis will force zero to be included in the axis.

y-max

The maximum value to render in the range axis.

y-min

The minimum value to render in the range axis.

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

y-title

The title to display on the range axis.

y-font

The font to render the range axis title in.

y-tick-interval

The numeric interval value to separate y-axis ticks in the chart.

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.

Common dataset properties

The following properties are common across all chart datasets:

Common Property Group

Property name

Description

name

The name of the chart's dataset, also referenced in the chart rendering properties.

Series Property Group

Property name

Description

series-by-value

If set, values entered act as the series name for the value columns provided.

series-by-field

If set, fields entered act as the series name for the value column provided. Setting this property will slice the value column into series groups.

Group Property Group

 

Property name

Description

reset-group

This property defines the group level at which the data should be reset.

group-by

This property defines the group level at which the data should be collected.

Advanced Property Group

 

Property name

Description

dependencyLevel

The dependency level field informs the reporting engine about the order in which the chart data source should be executed in relation to other items in the report. This is useful if you are using special functions that may need to be executed' prior to generating the data for the chart. The default value is set to 0.

Common category series dataset properties

The following properties are common across all charts that utilize category series dataset for populating the chart:

Common Property Group

Property name

Description

category-column

The data source column used to determine the category.

value-columns

The data source columns used to determine the chart values.

Common XY series dataset properties

The following properties are common across all charts that utilize the XY series dataset for populating a chart:

Common Property Group

Property name

Description

x-value-columns

The data source column that populates the X axis.

y-value-columns

The data source column that populates the Y axis.

Now that you've reviewed the common set of properties for all charts, you'll begin to explore the individual charts, including going through their configurable properties, as well as providing a quick example.

Area chart

The area chart displays a category dataset as a line, with the area underneath the line filled in. Multiple areas may appear depending on the number of series provided. The area chart is useful for visualizing the differences between two or more sets of data. It utilizes the common properties defined in the previous tables, including the category series common properties. The area chart defines no additional properties.

Area chart example

This example will demonstrate the area chart's capabilities. First, you'll need a rich enough dataset to demonstrate this and all the other charts in this article. You'll reuse the ElectroBarn HSQLDB data source. To begin, launch Pentaho Report Designer and create a new report. Now, select the Data tab. Right-click on the Data Sets tree element, and select the JDBC data source. If ElectroBarn is not already configured as a connection type, click the Connections add image button and fill in the following values, customizing the database location for your particular environment:

Connection Name

ElectroBarn

Connection Type

Hypersonic

Host Name

file:

Database Name

c:pathtochapter3dataelectrobarn

Port Number

<BLANK>

Username

sa

Password

<BLANK>

Click the Test button to verify your connection, and then click OK when you are done.

You need to define a SQL statement to populate your chart. You'll define a simple query that takes a look at the inventory data. Add a new query with the following SQL code:

SELECT
"INVENTORY"."ITEMCATEGORY",
"INVENTORY"."SALEPRICE",
"INVENTORY"."COST"
FROM
"INVENTORY"
ORDER BY
INVENTORY"."ITEMCATEGORY" ASC

Click OK. You're now ready to add a chart to your empty report. For this example, select the Chart report element Pentaho Reporting 3.5 for Java Developers  from the palette and drag it into the Report Header. Double-click on the chart, or right-click on the chart and select Chart…. Once the Edit Chart dialog appears, select the Area Chart Pentaho Reporting 3.5 for Java Developers  .

In the Primary DataSource tab, select the ITEMCATEGORY data field as your category-column. For your value-columns, select SALEPRICE and COST. Enter the strings Sale Price and Cost as the series–by-value values. When rendering an area chart, the order of value columns is important. If a larger value is rendered after a smaller value, the smaller value will not appear on the chart.

Once you configured the data for the chart, you can also make some customizations to the rendering. Set horizontal to True, as well as specifying the bg-color as yellow. Finally, set the show-legend property to True. Click the OK button and then preview your report to see the results!

Pentaho Reporting 3.5 for Java Developers

Bar chart

The bar chart displays individual bars broken out into individual categories and series. Bar charts are useful for comparing relative sizes of data across categories. The bar chart utilizes the common properties defined earlier, including the category series common properties.

The bar chart defines the following additional rendering properties:

Options Property Group

Property name

Description

bar-borders

If set to False, clears the default rendering value of the chart border. Identical to the plot-border property.

max-bar-width

The maximum width of a bar in pixels. Unless set, bars will generally expand to the available space within the chart.

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.

Bar chart example

You'll now build an example bar chart. Create a new report with the ElectroBarn data source, and use the following SQL query, which investigates purchase quantity and payment type:

SELECT
"INVENTORY"."ITEMCATEGORY",
"PURCHASES"."PAYMENTTYPE",
"PURCHASEITEMS"."QUANTITY"
FROM
"PURCHASES" INNER JOIN "PURCHASEITEMS" ON
"PURCHASES"."PURCHASEID" = "PURCHASEITEMS"."PURCHASEID"
INNER JOIN "INVENTORY" ON "PURCHASEITEMS"."ITEMID" =
"INVENTORY"."ITEMID"
ORDER BY
"INVENTORY"."ITEMCATEGORY" ASC,
"PURCHASES"."PAYMENTTYPE" ASC

Place a Chart element in the Report Header of the report, selecting bar Pentaho Reporting 3.5 for Java Developers  as its type. To begin, configure the dataset properties for your bar chart. Set category-column to ITEMCATEGORY, value-columns to QUANTITY, and series-by-field to PAYMENTTYPE. By setting the series-by-field property, the chart will create a series for each PAYMENTTYPE in the dataset.

Now, you'll customize the look of your chart. First, set the X-Axis show-labels property to True and text-format to {2}. This will display the value of each bar at the top of the bar. Then set max-label-width to 2.0, so that you can easily see all the category names in the chart. Finally, set the show-legend to True, in order to see what types of payments map to which bar color. You're now ready to preview your chart!

Pentaho Reporting 3.5 for Java Developers

Line chart

The line chart displays connected lines between categories for each series provided. This chart is useful for visualizing trends. The line chart utilizes the common properties defined in the previous tables, including the category series common properties. The line chart defines the following additional rendering properties:

Options Property Group

Property name

Description

line-style

The style of line to draw. Appropriate values for this property are solid, dash, dot, dashdot, and dashdotdot.

line-size

The thickness of the line to draw in pixels.The default value is set to 1.

show-markers

If set to True, displays markers at each category location within the line.

Note that the stacked and stacked-percent properties do not apply to the line chart type.

Line chart example

In this example, reuse the SQL query and dataset sections from your area chart example. Select the Line chart type Pentaho Reporting 3.5 for Java Developers  , and customize the chart with show-markers set to True as well as line-size set to 4.0. The result should look like this:

Pentaho Reporting 3.5 for Java Developers

Pie chart

The pie chart displays a sliced, multi-colored pie with individual slices consisting of individual series information. The pie chart uses its own dataset type, versus using a category or XY series dataset. The pie chart utilizes the common properties defined above, but does not utilize the category or XY dataset properties. Instead, it defines its own properties for providing chart data using the PieDataSetCollector. The pie chart defines the following rendering properties:

Required Property Group

Property name

Description

ignore-nulls

If set to False, the pie chart will render series data containing null values as a point in the pie chart, otherwise it will ignore the series item and will not render it.

ignore-zeros

If set to False, the pie chart will render series data containing zero values as a point in the pie chart, otherwise it will ignore the series item and will not render it.

Options Property Group

Property name

Description

slice-colors

The color in which to render each slice of the pie. The default for the first three series colors are red, blue, and green.

explode-pct

The percentage value to extract the sliced segment out of the main pie chart. This is used only if explode-slice is set.

explode-slice

The slice to extract from the pie chart, starting with zero. The values minValue or maxValue may be used instead, which select the minimum or maximum slice from the pie.

label-format

The pie label format string has a default value of {0}, and can reference the following fields:

  • {0}: Series name
  • {1}: Series raw value
  • {2}: Percentage value
  • {3}: Total raw value

rotate-clockwise

If set to True, the pie's series are laid out in a clockwise fashion, otherwise the series are laid out counter clockwise. This property defaults to True.

Legend Properties

Property name

Description

legend-label-format

The pie legend label format string has a default value of {0}, and can reference the same fields as Pie Label Format.

Note that the pie chart does not share the common properties horizontal, series-color, stacked, or series-names. The pie chart defines the following dataset properties:

Required Property Group

Property name

Description

series-by-field

The data source column used to determine the pie slice series.

value-column

The data source column used to determine the pie slice percentages.

Pie chart example

For the pie chart example, you'll compare the various costs of inventory items to one another by category. First, you'll need to define an SQL query as shown next:

SELECT
"INVENTORY"."ITEMCATEGORY",
"INVENTORY"."ITEMNAME",
"INVENTORY"."COST"
FROM
"INVENTORY"
ORDER BY
"INVENTORY"."ITEMCATEGORY" ASC,
"INVENTORY"."ITEMNAME" ASC

You'll then need to define a Group Header for your report. Right-click on the Groups section within the report structure and edit the root group, naming the group Item Category. Select the ITEMCATEGORY field as the only field in the Selected Items list. Expand the Group node in the structure tree, and select the Group Header. Now, uncheck the hide-on-canvas property, so you can view the Group Header in the canvas.

Drag-and-drop the ITEMCATEGORY field at the top of the Group Header. Place a chart below the text field, and click Edit Chart...

Select the Pie chart type Pentaho Reporting 3.5 for Java Developers  . You'll start configuring the chart by selecting the correct dataset. For the value-column, select the COST field. For the series-by-field property, select the ITEMNAME field.

You'll also need to tell the chart collector to reset the data after each group. Set the reset-group property to the already defined Item Category group.

Finally, you'll want to customize some of the rendering properties. Set the explode-slice to maxValue, and set the explode-pct to 0.5. This will highlight the most expensive item in each category. Also set show-legend to False to hide the legend and show-labels to True to display the individual pie slice labels.

Click the OK button and preview the report. You should see a group of charts as shown in the following figure:

Pentaho Reporting 3.5 for Java Developers

>> Continue Reading: Including Charts and Graphics in Pentaho Reports (Part 2)

If you have read this article you may be interested to view :

Pentaho Reporting 3.5 for Java Developers Create advanced reports, including cross tabs, sub-reports, and charts that connect to practically any data source using open source Pentaho Reporting.
Published: September 2009
eBook Price: $26.99
Book Price: $44.99
See more
Select your format and quantity:

About the Author :


Will Gorman

Will Gorman is an Engineering Team Lead at Pentaho. He works on a variety of Pentaho's products, including Reporting, Analysis, Dashboards, Metadata, and the BI Server. Will started his career at GE Research, and earned his Masters degree in Computer Science at Rensselaer Polytechnic Institute in Troy New York. Over the years, Will has given many talks, including topics at local Java User Groups. He has published technical papers in journals such as Neurology, and is the author of multiple patents. Will is originally from Cincinnati and now lives in Orlando, Florida, the headquarters of Pentaho.

Books From Packt

Flex 3 with Java
Flex 3 with Java

Spring Web Flow 2 Web Development
Spring Web Flow 2 Web Development

LWUIT 1.1 for Java ME Developers
LWUIT 1.1 for Java ME Developers

JasperReports 3.5 for Java Developers
JasperReports 3.5 for Java Developers

Solr 1.4 Enterprise Search Server
Solr 1.4 Enterprise Search Server

Asterisk 1.4 – the Professional’s Guide
Asterisk 1.4 – the Professional’s Guide

ASP.NET 3.5 CMS Development
ASP.NET 3.5 CMS Development

Drools JBoss Rules 5.0 Developer's Guide
Drools JBoss Rules 5.0 Developer's Guide

 

Your rating: None Average: 1.5 (2 votes)

Post new comment

CAPTCHA
This question is for testing whether you are a human visitor and to prevent automated spam submissions.
d
3
s
u
b
n
Enter the code without spaces and pay attention to upper/lower case.
Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Resources
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software