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:
| 1. | Select your chart in Design view. |
| 2. | On the Chart tab of Properties view, click Add 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: |
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. 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:
| 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
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); } } }}[/code]
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" } ] } ]}[/code] |
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: |
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. |
| 4. | In the Select Destination Dialog, browse to the location of your JSON file. |
| 6. | Click OK again to close the Preferences dialog. |
Recommended Comments
There are no comments to display.