Package net.sf.jasperreports.charts
Contains interfaces for chart plots and chart datasets.
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:
For each type of chart there is a special JRXML tag that groups various chart settings, including the dataset and the plot.
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
Chart-specific settings that apply to all types of charts are grouped under a special JRXML tag called
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
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
The global chart theme can be overridden at report level using the following report property in the report template:
If needed, at chart element level, the chart theme is specified using the
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
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
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)
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 chartcustomizerClass
: attribute that specifies the name of a chart customizer classrenderType
: attribute that specifies the chart rendering typetheme
: attribute that specifies the name of a custom chart themechartTitle
: element to customize the chart titlechartSubtitle
: element to customize the chart subtitlechartLegend
: 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 theRenderable
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 APIimage
: an image is first produced from the chart and this image in turn gets rendered onto the target graphic contextsvg
: 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
andforegroundAlpha
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 theseriesOrder
attribute and appear in that order when coloring the series.
-
Interface Summary Interface Description ChartContext ChartCopyObjectFactory ChartsAbstractObjectFactory ChartTheme Chart themes give more control over chart output, including the creation of the JFreeChart object itself.ChartThemeBundle ChartVisitor ElementVisitorAdapter JRAreaPlot Area charts and Stacked Area charts rely on this plot to render their axes and items.JRBar3DPlot Deprecated. To be removed.JRBarPlot Type of plot used to render Bar, Stacked Bar, and XY Bar charts.JRBubblePlot Only Bubble charts use this type of plot.JRCandlestickPlot The Candlestick plot is also an axis-oriented plot and allows you to customize axis labels using expressions.JRCategoryAxisFormat JRCategoryDataset This dataset accommodates one or more data series consisting of values associated with categories.JRCategoryPlot Type of plot used for rendering category charts.JRCategorySeries Represents the series for any Category dataset.JRChart Implementations of this interface can be used for rendering chart components.JRChartAxis Describes an axis that can be added to a multiple axis chart.JRChartCustomizer This interface allows users to provide pluggable chart customizers.JRChartDataset Datasets are used to represent the actual data needed to generate a chart.JRChartPlot Chart plots define chart appearance and display details such as colors, legend or labels.JRChartPlot.JRSeriesColor JRCommonLinePlot Type of the plot used to render Line, XY Line and Scatter charts.JRDataRange Represents a numeric range.JRGanttDataset This dataset accommodates one or more data series consisting of values associated with tasks and subtasks.JRGanttSeries Represents the series for the Gantt dataset.JRHighLowDataset Although the name of this dataset is "High-Low", it can actually hold a series of (x, high, low, open, close, volume) items.JRHighLowPlot Used only in combination with High-Low charts, this type of plot lets users customize the labels for both axes, like all the other axis-oriented plots.JRItemLabel Contains the formatting option for the textual representation of item labels in a category plotJRLinePlot Type of plot used to render Line charts.JRMeterPlot This type of plot can be used only for Meter charts and represents the display options of a Meter Chart.JRMultiAxisPlot Represents the display options and nested charts of a multiple axis chart.JRPie3DPlot Deprecated. To be removed.JRPieDataset This dataset is useful for rendering Pie charts.JRPiePlot Type of plot used for rendering Pie charts.JRPieSeries Represents the series for the Pie dataset.JRScatterPlot Scatter plots are used only with Scatter charts.JRThermometerPlot Represents the display options of a Thermometer chart.JRTimeAxisFormat JRTimePeriodDataset The Time Period dataset is very much like the Time Series dataset in that it wraps series consisting of (time period, numeric value) pairs.JRTimePeriodSeries Represents the series for the Time Period dataset.JRTimeSeries Represents the series for the Time Series dataset.JRTimeSeriesDataset This dataset wraps one or multiple time series.JRTimeSeriesPlot This type of plot is similar to the Line plot and Scatter plot in that it lets users configure the labels for both axes, the rendering of lines to connect the item points, and the rendering of the small shapes that mark each item point on the target plot area.JRValueAxisFormat JRValueDataset This class represents a dataset that consists of a single value.JRValueDisplay Represents the formatting option for the textual representation of a value displayed in a Meter or Thermometer chart.JRXAxisFormat JRXyDataset This dataset is a wrapper for data series made of (x, y) value pairs and is used for rendering XY Bar, XY Line, XY Area, and Scatter Plot charts.JRXySeries Represents the series for the XY dataset.JRXyzDataset The XYZ dataset wraps series consisting of (x, y, z) items.JRXyzSeries JRYAxisFormat NamedChartCustomizer Interface that represents aJRChartCustomizer
that is assigned a name after being instantiated using the default empty constructor. -
Class Summary Class Description ChartsElementsVisitor Chart element visitor.ChartsExpressionCollector An expression collector traverses a report and collects report expressions out of it.ChartsExtensionsRegistryFactory ChartVisitorFactory DefaultElementVisitorsAdapter JRAbstractChartCustomizer Abstract implementation ofJRChartCustomizer
that provides access to parameter, variable and field values.