HOWTO: Integrate the JasperReports Chart Theme Engine

July 20, 2009

by Jason Buberel

4 comments

Another new feature introduced in the JasperReports engine (v3.5.2) is support for chart themes. The companion GUI report build product, iReport, offers a reasonable first-version chart theme editor. The theme editor allows you to customize axis formatting (currency and date formats, for example), plot line styles and colors, etc. The only problem is that the chart theme engine is not fully integrated into the base JasperReports engine.

This makes it a bit tricky to get the two parts working in a fully automated runtime environment. But here is how we pulled it off.

The key to pulling this off came when we realized that the chart theme support code is packaged as part of the demo/sample code that comes with the JasperReports v.3.5.2 source code download (look for the file named -project.zip, that includes full source code for all demo/sample applications). The demo code you’re interested in using is located in the directory:

jasperreports-3.5.2/demo/samples/chartthemes

This does come with instructions on how to compile the source into a library (.jar) that you can use with your project. If you’re lazy, you can alternatively download the iReport runtime distribution which includes a pre-built version of the library named:

iReport-nb-3.5.2-src/ireport/modules/ext/jasperreports-chart-themes-3.5.2.jar

So either read the README that comes with the chartthemes sample code to build your own .jar file, or use the one that comes packaged with iReport. Your choice. We’ll come back to this later.

Before attempting to integrate the chart theme engine into your JasperReport runtime environment, you need to create a report (a .jrxml file) that contains a chart that makes use of a custom chart theme (.jrctx). There are quite a few steps in that process, so I’ll just refer you to the iReport user manual and assume that you have successfully used iReport to create your report template and your custom chart theme. Once you have those two files in hand, you can proceed to the next step.

To start, you’ll need to add several libraries to your JasperReports runtime environment and classpath in order to enable chart theme support. Those .jar files are:

jasperreports-chart-themes-3.5.2.jar
castor-1.2.jar (from the jasperreports-3.5.2/demo/samples/chartthemes/lib directory)
spring-beans.jar (from the jasperreports-3.5.2/lib directory)
spring-core.jar (from the jasperreports-3.5.2/lib directory)

Next, you need to create a new file named ‘jasperreports_extensions.properties’. This file should be located (once deployed) in the same directory as your ‘jasperreports.properties’ file is currently. This file is used to tell the JasperReports engine that you are enabling an extension to the core to support chart themes. The contents of this file should be approximately as follows:

net.sf.jasperreports.extension.registry.factory.xml.chart.themes= \
net.sf.jasperreports.chartthemes.simple.XmlChartThemeExtensionsRegistryFactory
net.sf.jasperreports.xml.chart.theme.mycustomtheme=/the/path/to/mycustomtheme.jrctx

The first line tells the JasperReports engine that you are adding an extension to the core framework, and that the class for invoking the extension is named ‘XmlChartThemeExtensionRegistryFactory’. The second line will then configure that chart engine with a chart theme named ‘mycustomtheme’ and will provide it with the information necessary to locate the .jrctx file that resulted from creating your custom theme using the iReport GUI chart theme designer tool. In your report template (.jrxml) file, you will see this chart them referenced by your chart:

When the JasperReports engine comes across the ‘theme’ attribute, it will know to refer the handling of that attribute to the charttheme extension. And the charttheme extension has now been configured to know exactly where your chart theme is located. And voila, it all works. You should now be able to feed your .jrxml into the standard fillReport() methods provided by JasperReports, and get your custom theme charts rendered correctly.

Previous post:

Next post: