Chart Customizers

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.

Chart customizers were enhanced in JasperReports Library version 6.3.1. New customizer classes were added and configurable customizers are now supported. Jaspersoft Studio now supports a simplified 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 in Jaspersoft Studio 6.4 and Higher

To apply an existing customizer to a chart:

1. Select your chart in Design view.
2. On the Chart tab of Properties view, click New next to the Chart Customizers section.

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

Chart customizer selection dialog

3. Select a chart customizer from the list.

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

4. Click Next if it 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

5. Fill in the properties as prompted by the user interface. For example, the following values for Legend Shape change the legend to an circle:
     Apply to – All Items
     Shape Type – Ellipse
     Width – 10
     Height – 10
6. Click Finish.

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

Result of chart customizer

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:

1. Add the customizer jar to your classpath.
2. Select the chart in Design view.
3. In the Advanced tab of Properties view, click next to Common Chart Properties> Customizer Class.

The Open Type dialog is displayed.

4. Enter the name of your class in the Open Type dialog and click OK.

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.

JasperReports Library 6.4 introduced new 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.

Prior to Jaspersoft Studio 6.4, you could only use hard-coded values in your chart customizer. As of Jaspersoft Studio 6.4, you can create configurable chart customizers.

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:

1. Create and compile the customizer and add the jar to your classpath. For information about compiling your files with Jaspersoft Studio and Eclipse, see Working with Java in Eclipse.
2. Create a JSON file that references your customizer and defines its UI.
3. Add the JSON file to the Jaspersoft Studio user interface.

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:

Constants in AbstractAxisCustomizer class

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.

RangeAxisCustomizerSample

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 a 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:

label – Name for the customizer in the chart customizer selection dialog box.
description – Text that appears upon hover.
customizerClass – Full class name of your customizer.
supportedPlot – Array of chart types supported by the customizer. Chart types are designated by a numeric code, shown in the following table.

Chart Codes for supportedPlot in JSON Files

Chart Type Code in JasperReports
CHART_TYPE_AREA 1
CHART_TYPE_BAR3D 2
CHART_TYPE_BAR 3
CHART_TYPE_BUBBLE 4
CHART_TYPE_CANDLESTICK 5
CHART_TYPE_HIGHLOW 6
CHART_TYPE_LINE 7
CHART_TYPE_PIE3D 8
CHART_TYPE_PIE 9
CHART_TYPE_SCATTER 10
CHART_TYPE_STACKEDBAR3D 11
CHART_TYPE_STACKEDBAR 12
CHART_TYPE_XYAREA 13
CHART_TYPE_XYBAR 14
CHART_TYPE_XYLINE 15
CHART_TYPE_TIMESERIES 16
CHART_TYPE_METER 17
CHART_TYPE_THERMOMETER 18
CHART_TYPE_MULTI_AXIS 19
CHART_TYPE_STACKEDAREA 20
CHART_TYPE_GANTT 21
sections – Property that controls the display of the user interface. Has the following attributes:
name – Name for the user interface dialog box.
expandable – Boolean; for chart customizers, always set to false.
properties – Attribute that contains sections to define each entry box in the user interface. Each entry box has the following attributes:
name – Name of the argument to pass to the customizer class.
label – Name that appears in the user interface.
description – Tooltip that appears on hover.
mandatory – Boolean. When true, the property is required; when false, property is optional.
readOnly – Sets attribute as read-only. Not used for chart customizers.
type – Type of the attribute, as expected by the customizer class.
defaultValue (optional) – Default value for an optional property.

To add a non-configurable customizer, use an empty list for the properties. For example:

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

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

1. Select Window > Preferences (Eclipse > Preferences on Mac).
2. In the Preferences dialog, select Jaspersoft Studio > Report Designer > Chart Customizers.
3. Click Add.
4. In the Select Destination Dialog, browse to the location of your JSON file.
5. Click OK.
6. Click OK again to close the Preferences dialog.

Version: 
Feedback