Useful Chart Customizers in JasperReports, iReport, and JasperReports Server

In a previous article I described some reasons that chart customizers are useful and gave some links to useful resources. (I’ll call that article “Chart Customizers 1″.) If you are not already familiar with chart customizers, then please read Chart Customizers 1 before reading this one. If you are already familiar with them, then please skim Chart Customizers 1 before reading this one.

Overview

“Chart Customizers 1″ explained what chart customizers are and provided some code. It was useful for Java developers. It made all changes as hard-coded settings, so the samples were not immediately useful for anyone without further coding.

“Chart Customizers 2″ (this article) provides a useful chart customizer and describes why it’s useful. You can immediately use it to solve some common problems (no coding required!).

If you just want to grab the chart customizer (binary and source) scroll all the way to the bottom.

Using Additional Properties

The concept of “properties” is a key idea that was missing in “Chart Customizers 1″. Using properties lets you set values in the report (in the .jrxml file) rather than hard-coding them as I did in my earlier sample. As one would hope (expect?) it’s simple. The chart customizer extends JRAbstractChartCustomizer. Therefore we can get the chart properties like this:

JRPropertiesMap pm = jasperChart.getPropertiesMap();

Then we can get a particular property like this:

double upperMargin = (pm.getProperty("UpperMargin") == null) ? -1 : Double.parseDouble(pm.getProperty("UpperMargin"));

This is the addition that made it possible for me to extend my chart customizers from being purely proof of concept samples to being useful chart customizers.

Bar Chart Improvements

Integer Tick Marks

Let’s start with some common requests for bar charts. Perhaps the most common request that I have seen is to prevent charts from showing non-integer values on value axis. Here’s an example. The number of times that a person shopped on a particular day is necessarily an integer. I don’t want to see “2.5″ on the chart axis.

The bars are completely accurate. Yet it's annoying to have the non-decimal value displayed.

How easy is it to tell JFreeChart to only use integers? Really easy! Hooray! It has a method called “createIntegerTickUnits()”. By the way, if you’re doing any significant work with JFreeChart then you should buy their Developer Guide. It’s well done.

How easy is it tell iReport and JasperReports to use only this method? Impossible. That’s a big bummer.

Fortunately, we can amend that somewhat pessimistic answer like this:

How easy is it tell iReport and JasperReports to use only integers? Really easy if we use a chart customizer! Hooray! It’s a single line. Since we might not always want this applied, we can surround it by an if statement:

if (useIntegerTickUnits) {
	valueAxis.setStandardTickUnits(NumberAxis.createIntegerTickUnits());
}

Now if I add the property “IntegerTickUnits” with the value “true” to my bar chart I’ll only get integers.

On the chart "Shopping Days" I set this property

If I set the value to “false” (or to anything besides “true”) or if I don’t set the property at all, then I get the standard behavior. If you’re new to JasperReports Server then refer to the Detailed Steps at the end of this article to exactly exactly what you need to do to apply this chart customizer.

The bars look much better when aligned with tick marks (or exactly half way between them)

Category Labels on multiple lines

By default there is no way to tell the chart to use multiple lines to display a category label. Again it’s easy in JFreeChart, so it’s easy in a chart customizer. Now I just have to add the property “MaximumCategoryLabelLines” with the value “2″ to my chart to get what I want.

Who is it that drank more ţuică?

Now its clear that I ate more hot dogs.

Using more space for category labels

JFreeChart is nice enough to truncate long labels for me. But it’s quite restrictive about how large it lets the labels be. A call to setMaximumCategoryLabelWidthRatio let’s me allot more space for the labels. Here’s an alternative solution to the previous problem where labels are cut off.

Who is it that ate more hot dogs?

Alternative solution increases the width allowed for the labels

Space between bars

The default amount of space put between the bars within each category is pretty generous. That can be reduced as a percentage of the available space. I added this to the .jrxml (well, iReport adds this to the .jrxml) to completely eliminate the space between bars:

<property name="ItemMargin" value="0.0f"/>

In some charts its more effective to remove the space between bars

Upper Margin

I will not bother showing this property since it’s covered in “Chart Customizers 1″. The only difference now is that in that case I hard-coded the margin to .40. Now I can set that percentage as a property in the chart.

Pie Chart Improvements

My most common annoyance with pie charts was when I put several pie charts onto the same page to show a trend. There is no easy way to specify a color for a named section. It’s easy to specify a color for the first section and a color for the second section. This is often sufficient. But this has the potential to be extremely confusing when two different charts have different items or when they have the same items returned in a different order. The following sample report shows the idea clearly.

Passing in the colors for the sections in a pie chart is the most complex piece in all of my chart customizers. I give a special thank you to Teodor Danciu for the idea and to Luke Shannon for help with some implementation details.

You must create a property on the chart called “Predefined Colors”. The property value is a String containing key:value pairs separated from each other by semi-colons. For example, for a report that I run which shows the databases that JasperReports Server instances use for their repository database I pass this string:

MySQL:#015A84;Oracle:red;PostgreSQL:#0085B0;Microsoft SQL Server:#F8EB33

For most databases I choose a color using RGB values. For Oracle I use the shorthand syntax “red”. These values get converted into colors using a utility class that is built-in to JasperReports: http://jasperreports.sourceforge.net/api/net/sf/jasperreports/engine/type/ColorEnum.html

To see exactly how it’s done, refer to the sample report (Pie_Specified_Series_Colors.jrxml) and to the comments in the chart customizer (PieLabels.java).

These are some of the most common chart tweaks that I have seen. Some are ones that I have needed myself, and others are ones that I have seen requested on JasperForge. Please let me know if you find the chart customer useful, and let me know what other properties you would find useful in a chart customizer.

Detailed Steps to update a report

Here are the steps I followed to apply my new chart customizer to an existing report. This is the report “Customer Overview” that ships with Jaspersoft BI evaluation version. So you can easily apply this chart customizer to that sample before trying it on your own charts.

1. Upload ChartCustomizers2.jar into JasperReports Server. (Use either the web UI or iReport’s JasperReports Server plug-in.)
2. Edit the report to add a link to the resource ChartCustomizers2.jar. (Use either the web UI or iReport’s JasperReports Server plug-in.)
3. Edit the report in iReport to make two changes:
1. Find the property “Customizer Class” and set it to “com.jaspersoft.bizdev.BetterBarLabels” (without the quotes).
2. Find the property “Properties expressions” and add a new property called “IntegerTickUnits” with the value “true” (without the quotes in both cases).
4. Save the report back to JasperReports Server. Run the report.

Sample reports and the Chart Customizer

WordPress seems to lose my attachments with some regularity. So instead of using that I’ll try GoogleDocs for sharing my samples.

• Chart Customizer 2 – This is a .jar file. Just add it to your classpath and you can use it. The .jar also includes the source .java files.
• Pie Chart sample report JRXML
• Pie Chart sample report PDF

Advertisement