Package net.sf.jasperreports.charts

Contains interfaces for chart plots and chart datasets.

The Built-In Chart Component

JasperReports provides built-in support for charts using the chart component based on the JFreeChart library. It exposes a limited set of visual properties that the charting package actually supports. This limited set should be sufficient for the majority of users, and in the future it may be extended to accommodate community feedback and requests.
With the built-in chart component, users only have to apply the desired visual settings and define the expressions that will help the engine build the chart dataset incrementally during the iteration through the report data source.
When including and configuring a chart component, three entities are involved:
  • The overall chart component
  • The chart dataset (which groups chart data-related settings)
  • The chart plot (which groups visual settings related to the way the chart items are rendered)
JasperReports currently supports the following types of charts: Pie, Pie 3D, Bar, Bar 3D, XY Bar, Stacked Bar, Stacked Bar 3D, Line, XY Line, Area, Stacked Area, XY Area, Scatter Plot, Bubble, Time Series, High-Low-Open-Close, Candlestick and Gantt.
For each type of chart there is a special JRXML tag that groups various chart settings, including the dataset and the plot.

Chart Properties

All chart types have a common set of properties. Charts are normal report elements, so they share some of their properties with all the other report elements. Charts are also box elements and can have hyperlinks associated with them.
Charts resemble text fields and images in that they can postpone their actual rendering until all the data needed for this operation becomes available to the reporting engine. Data needed by a chart is gathered by the associated dataset during iteration through the report data. However, there are situations that require displaying charts at the beginning of a document, where the necessary data is not yet available, given the way the engine process data and renders the final document.
In such cases, the chart evaluation can be postponed using the evaluationTime and evaluationGroup attributes, which work in the same manner as for text fields and images.
Chart-specific settings that apply to all types of charts are grouped under a special JRXML tag called <chart>:
  • isShowLegend: flag attribute that specifies if the legend is visible on the chart
  • customizerClass: attribute that specifies the name of a chart customizer class
  • renderType: attribute that specifies the chart rendering type
  • theme: attribute that specifies the name of a custom chart theme
  • chartTitle: element to customize the chart title
  • chartSubtitle: element to customize the chart subtitle
  • chartLegend: element to customize the chart legend

Chart Rendering

In generated reports the output produced by a chart element is an image element. Image elements are drawn using implementations of the Renderable interface. The renderType attribute specifies the renderer implementation that will be used to render the chart during export or report display. By default, JasperReports recognizes the following values for this attribute:
  • draw: the chart is drawn directly on the target graphic context using the JFreeChart API
  • image: an image is first produced from the chart and this image in turn gets rendered onto the target graphic context
  • svg: the chart is transformed into the SVG format and from that format is then rendered onto the target graphic context

Chart Title, Subtitle and Legend

All charts can have a title, a subtitle and a legend. All of them are optional and can be customized for color, font, and position.

Chart Customizer and Chart Themes

To provide full control over chart customization even when using the built-in chart component, JasperReports can make use of either a chart theme implementation, or of a chart customizer implementation associated with the chart element, or both.
Chart themes are a more recent addition to the library and in a way they deprecate the chart customizers because they bring enhanced capabilities in controlling chart output.
A chart customizer is an implementation of the JRChartCustomizer interface that is associated with the chart element using the customizerClass attribute. The easiest way to implement this interface is by extending the JRAbstractChartCustomizer class and thus having access to parameters, fields, and variables, for more flexible chart customization based on report data.
Chart customizer only allow modifying the JFreeChart object that is created externally and passed in to them.
Chart themes give more control over chart output, including the creation of the JFreeChart object itself. Also, chart themes affect a whole range of chart types across multiple reports and are not necessarily tied to a specific chart element within a report. They can even apply globally to all charts within a given JasperReports deployment, applying a new look and feel to all charts created.
A chart theme can be set globally using a configuration property within the jasperreports.properties file as follows:

net.sf.jasperreports.chart.theme=theme_name

The global chart theme can be overridden at report level using the following report property in the report template:

<property name="net.sf.jasperreports.chart.theme" value="theme_name"/>

If needed, at chart element level, the chart theme is specified using the theme attribute.

Chart Datasets

One of the most important considerations when putting a chart element into a report template is the data mapping. The chart will need to extract its data from whatever data is available inside the report at runtime.
The data-oriented component for mapping report data and retrieving chart data at runtime is the chart dataset. A chart dataset is an entity that somewhat resembles a report variable because it gets initialized and incremented at specified moments during the report-filling process and iteration through the report data source.
Like a report variable, at any moment a chart dataset holds a certain value, which is a complex data structure that gets incremented and will be used for rendering the chart at the appropriate moment.
Several types of chart datasets are available in JasperReports because each type of chart works with certain datasets: Pie, Category, XY, Time Series, Time Period, XYZ, High-Low and Gantt.
The JasperReports object model uses the JRChartDataset interface to define chart datasets. There are implementations of this interface for each of the aforementioned dataset types. All chart datasets initialize and increment in the same way, and differ only in the type of data or data series they map. Common dataset properties are grouped under the <dataset> tag in JRXML format.

Chart Plot

The chart plot is the area of the chart on which the axes and items are rendered. Plots differ based on the type of chart. Some plots specialize in drawing pies; others specialize in drawing bar items or lines.
Each type of plot comes with its own set of properties or attributes for customizing the chart's appearance and behavior.
There is, however, a subset of plot properties common to all plot types, exposed in the JRChartPlot interface. They are grouped under the <plot> tag in JRXML and can be part of any chart/plot definition in the report template:
Plot Background Color
The backcolor attribute can be used to specify the color used for drawing the plot's area background.
Plot Orientation
Some types of plots can draw their items either vertically or horizontally. For instance, Bar charts can display either vertical or horizontal bars. Pie charts do not use this setting, but since the majority of charts do have a concept of orientation, the attribute was included among the common plot settings.
Plot Transparency
When filling up the background with a specified color or drawing items on the target device, the plot can use a customizable degree of transparency, which you can control using the backgroundAlpha and foregroundAlpha attributes. These attributes accept numeric values ranging from 0 to 1. The default for both attributes is 1, which means drawings on the plot area are opaque.
Label Rotation
The text labels on the x axis of a chart can be rotated clockwise or counterclockwise by setting a positive or a negative numeric value representing the number of degrees to the labelRotation attribute of the plot. This attribute applies only to charts for which the x axis is not numeric or does not display dates.
Series Colors
To control the color of each series in a chart displaying multiple series, you can use the <seriesColor> tag available at the chart-plot level. If only one <seriesColor> tag is specified, it becomes the color of the first series. If more than one <seriesColor> tag is specified, the chart will cycle through the supplied colors.
Pie charts do not have multiple series, but they do need different colors for each slice, so the specified colors will be used. Meter and Thermometer charts do not have series and will ignore any <seriesColor> settings.
When used in a chart that is part of a Multiaxis chart, the series colors are treated a bit differently. The default color series to cycle through is defined in the plot of the Multiaxis chart, and the color series for the nested charts define series colors for that chart only. This is useful when a Multiaxis chart contains several line charts, each with one series. By default every line will be the first in its plot and will have the first color defined in the Multiaxis plot, so every line will be the same color. To solve this, a <seriesColor> can be set for each nested chart to override the default colors.
All series colors are sorted by the value of the seriesOrder attribute and appear in that order when coloring the series.