Chart Customizers

Chart customizers are Java classes that change the appearance of charts. Chart customizers let you implement JFreeChart functionality that has not been directly included in JasperReports. For example, you can use chart customizer classes to change the shape of the legend icons in a chart or change the colors or pattern of the bars in a bar chart.

Jaspersoft Studio provides a simple UI for applying chart customizers. This includes a number of out-of-the-box customizers for common configurations as well as a mechanism to let you add your own customizers to the UI. In addition, if you create a configurable customizer, that is, a customizer that lets the user set values in the report rather than hard-coding them, you can create a user interface for it using a JSON file.

Using Chart Customizers

Adding a Chart Customizer to a Chart

To apply an existing customizer to a chart:

The Select Chart Customizers dialog is displayed. By default, only chart customizers that support your current chart type are shown.

Chart customizer selection dialog

If the customizer is configurable and has a user interface, the Next button is available. Otherwise, the Finish button is available.

The user interface for the customizer is displayed. For example, the interface for Legend Shape is shown below.

User interface for a chart customizer

The customizer selection dialog box is closed and the customizer is applied to your chart. Click Preview to view your chart.

Adding a Customizer to a Chart in Earlier Versions of Jaspersoft Studio

You can add a customizer to a chart in an earlier version of Jaspersoft Studio using advanced properties. You cannot add more than one customizer and the customizer cannot be configurable. For more information about creating a customizer jar, see Creating a Chart Customizer:

The Open Type dialog is displayed.

Creating a Chart Customizer

To create a chart customizer, you must extend or implement JRAbstractChartCustomizer, which defines a customize method that takes a JFreeChart object and a JasperReports chart object as parameters. The customize method lets you access the settings for a chart. You can also create configurable chart customizers.

JasperReports Library provides customizer classes that extend JRAbstractChartCustomizer, which you can use for your chart customizers. To see the available customizer classes, see the Javadoc for the JasperReports Library API. You can also download the JasperReports Library source and look at the samples in the demo/samples/chartcustomizer directory.

Jaspersoft Studio uses a JSON descriptor format to register certain components and optionally create a UI for the component. This framework is used for JFreeChart customizers as well as being used internally.

Example of Creating a Customizer Class

The following example shows a customizer, RangeAxisCustomizerSample, and a JSON file for the user interface. This example allows the user to set the maximum and minimum values on the X and Y axis and to set the interval for the ticks on the Y axis.

To use this customizer in a report:

To create the example customizer class:

A customizer class takes two arguments, a JFreeChart and a JasperReports Chart object. The RangeAxisCustomizerSample customizer extends the AbstractAxisCustomizer class, which is an extension of JRAbstractChartCustomizer for working with axis properties. AbstractAxisCustomizer exposes three constants for a chart axis: the minimum and maximum values on the Y axis and the spacing of the ticks on the Y-axis display:

public static final String PROPERTY_MIN_VALUE = "minValue";
public static final String PROPERTY_MAX_VALUE = "maxValue";
public static final String PROPERTY_TICK_UNIT = "tickUnit";

A chart customizer defines a customize method that takes a JFreeChart object and a JRChart object. The customize method can access chart settings and make changes to them. During report execution, JasperReports calls the customize method for the chart and applies the settings, along with the settings from the JSON file. RangeAxisCustomizerSample is as shown below.

package com.jaspersoft.studio.sample.customizer;

import org.jfree.chart.JFreeChart;
import org.jfree.chart.axis.NumberAxis;
import org.jfree.chart.axis.ValueAxis;
import org.jfree.chart.plot.CategoryPlot;
import org.jfree.chart.plot.XYPlot;

import net.sf.jasperreports.customizers.axis.AbstractAxisCustomizer;
import net.sf.jasperreports.engine.JRChart;

/**
 * Customizer to define the minimum and maximum value of the domain axis, works for 
 * XY plot
 */
public class RangeAxisCustomizerSample extends AbstractAxisCustomizer
{
	@Override
	public void customize(JFreeChart jfc, JRChart jrc) 
	{
		ValueAxis valueAxis = null;

		if ((jfc.getPlot() instanceof XYPlot))
		{
			valueAxis = jfc.getXYPlot().getRangeAxis();
		}
		else if (jfc.getPlot() instanceof CategoryPlot)
		{
			valueAxis = jfc.getCategoryPlot().getRangeAxis();
		}

		if (valueAxis != null)
		{
			configValueAxis(valueAxis, PROPERTY_MIN_VALUE, PROPERTY_MAX_VALUE);

			if (valueAxis instanceof NumberAxis)
			{
				configNumberAxis((NumberAxis)valueAxis, PROPERTY_TICK_UNIT);
			}
		}
	}
}

Example of a JSON file for the user interface:

The following JSON file lets the user enter values for the configurable properties in RangeAxisCustomizerSample. The JSON file uses the generic framework for the Jaspersoft Studio user interface.

{
    "label": "Range Axis Range and Tick - Sample",
    "description": "Customizer to set the range for the axes and the tick spacing for an axis chart.",
    "customizerClass": "com.jaspersoft.studio.sample.customizer.RangeAxisCustomizerSample",
    "supportedPlot": ["13","14","15"],
    "sections": [
        {
            "name": "Customizer configuration",
            "expandable": false,
            "properties": [
				{
                    "name": "minValue",
                    "label": "Range Min",
                    "description": "The minimum value on the axis",
                    "mandatory": false,
                    "readOnly": false,
                    "type": "double"
                },
                {
                    "name": "maxValue",
                    "label": "Range Max",
                    "description": "The maximum value on the axis",
                    "mandatory": false,
                    "readOnly": false,
                    "type": "double"
                },
                {
                    "name": "tickUnit",
                    "label": "Distance",
                    "description": "The space between ticks.",
                    "mandatory": false,
                    "defaultValue": "1",
                    "readOnly": false,
                    "type": "double"
                }
            ]
        }
    ]
}

A JSON file for a chart customizer has the following members:

  "sections": [
        {
            "name": "Customizer configuration",
            "expandable": false,
            "properties": []
        }
    ]

To add a JSON UI definition file to the Report Designer: