Sample Reference - Schema Reference - Configuration Reference - API (Javadoc)
|
|
|
|
JasperReports - Charts Sample (version 4.0.1) | |
|
|
|
Main Features in This Sample | |
| Charts |
| Altering Charts (Chart Customizers) |
|
|
Secondary Features | |
Datasets |
|
|
|||||
top | ||||||
|
||||||
Charts | Documented by Sanda Zaharia | |||||
|
||||||
| Description / Goal |
| How to render different types of charts using the built-in chart element. | |||
| Since |
| 1.0.0 | |||
| Other Samples |
|
|
|||
|
||||||
|
Charts in JasperReports
The JasperReports library does not produce charts and graphics itself. However, it can easily integrate charts, barcodes, and graphics produced by other more specialized Java libraries. The great majority of available Java libraries that produce charts and graphics can output to image files or in-memory Java image objects. And such image objects can be integrated into a JasperReports document using a normal image element. To simplify the integration of charts inside reports, JasperReports provides a specialized <chart> element.
Chart Properties When including and configuring a chart component, three entities are involved:
Pie, Pie 3D, Bar, Bar 3D,
XY Bar, Stacked Bar, Stacked Bar 3D, Line, XY Line, Area, XY Area, Stacked Area, Scatter,
Bubble, Time Series, High-Low-Open-Close, Candlestick, Multiple Axis, Meter, Thermometer and Gantt.
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. Chart-specific settings that apply to all types of charts are grouped under a special JRXML tag called <chart> . It contains the following elements:
Chart Rendering In generated reports, the output produced by a chart element is an image element. Image elements are drawn using implementations of the JRRenderable interface. Charts have an attribute called renderType which 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:
Chart Title, Subtitle and Legend All charts can have one title and one subtitle. All chart types can display a legend that explains the values represented by the chart. By default all charts display the legend, but one can suppress this display by setting the isShowLegend flag to false .
Chart titles, subtitles and legends are optional and can be customized for color, font, and position. They can be placed at the top of the chart, at the bottom of the chart, or on the left or right side of the chart, depending on the value of the position attribute.
Chart Datasets Charts rely on a data-oriented component called the chart dataset for mapping report data and retrieving chart data at runtime. A chart dataset is an entity which can get 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, Value 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. The increment or reset type and increment or reset groups can be specified by setting the dataset common attributes below:
Pie Dataset A pie dataset is characterized by the following expressions:
Category Dataset A category dataset is characterized by the <categorySeries /> element, which contains:
XY Dataset An XY dataset is characterized by the <xySeries /> element, which contains:
XYZ Dataset An XYZ dataset is characterized by the <xyzSeries /> element, which contains:
Time Series Dataset A time series dataset is characterized by the timePeriod attribute, and the <timeSeries /> element.
The timePeriod attribute specifies the type of the data series inside the dataset. Time series can contain numeric
values associated with days, months, years, or other predefined time periods. Possible values are:
<timeSeries /> element contains:
Time Period Dataset An time period dataset is characterized by the <timePeriodSeries /> element which contains:
High Low Dataset An high low dataset is characterized by the following expressions:
Value Dataset This is a special chart dataset implementation that contains a single value and is used for rendering Meter and Thermometer charts. The value is collected using the <valueExpression /> expression.
Common Settings for Chart Plots 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. They are grouped under the <plot /> element in JRXML and can be part of any chart/plot definition in the report template. Common plot attributes are:
Specific Settings for Chart Plots
Chart Types
Running the sample requires the Apache Ant library. Make sure that ant is already installed on your system (version 1.5 or later).
In a command prompt/terminal window set the current folder to demo/hsqldb within the JasperReports source project and run the > ant runServer command.
It will start the HSQLDB server shipped with the JasperReports distribution package. Let this terminal running the HSQLDB server.
Open a new command prompt/terminal window and set the current folder to demo/samples/charts within the JasperReports source project and run the > ant test view command.
It will generate all supported document types containing the sample report in the demo/samples/charts/build/reports directory.
Then the report will open in the JasperReports internal viewer. |
|||||
|
||||||
top | ||||||
|
||||||
Altering Charts (Chart Customizers) | Documented by Sanda Zaharia | |||||
|
||||||
| Description / Goal |
| How to make various changes to a generated chart using the JFreeChart API, which is used by JasperReports to draw the charts created with the built-in chart element. | |||
| Since |
| 1.1.1 | |||
| Other Samples |
|
|
|||
|
||||||
|
Chart Customizers and Chart Themes
Although the JFreeChart library is a fairly complete charting package that offers great flexibility and a comprehensive range of settings to fully customize the appearance and the content of the charts it renders, the built-in chart component offered by JasperReports exposes only a subset of the library’s original charting functionality. This ensures that JasperReports charts are easily embeddable into reports and that the basic set of properties exposed through JRXML and the object model is enough for the majority of use cases. In time, other JFreeChart settings will be exposed through the built-in chart component, but certainly JasperReports will never be able to expose all the JFreeChart settings through JRXML tags or the API. 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
having access to parameters, fields, and variables, for more flexible chart customization
based on report data.
However, it is recommended to implement and work with chart themes instead of chart customizers, because chart themes give more control over chart output, including the creation of the JFreeChart object itself. Chart customizer only allow modifying the JFreeChart object that is created externally and passed in to them. 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 within that environment. A Simple Chart Customizer Class Example When one implements the JRChartCustomizer interface, the only method which has to be implemented is: public void customize(JFreeChart chart, JRChart jasperChart);
The Charts sample contains a very simple customizer class, which sets specific colors for series in a Bar chart. First, let's take a look at the BarChartCustomizer class in the src directory:
import java.awt.Color; import net.sf.jasperreports.engine.JRChart; import net.sf.jasperreports.engine.JRChartCustomizer; import org.jfree.chart.JFreeChart; import org.jfree.chart.renderer.category.BarRenderer; public class BarChartCustomizer implements JRChartCustomizer { public void customize(JFreeChart chart, JRChart jasperChart) { BarRenderer renderer = (BarRenderer) chart.getCategoryPlot().getRenderer(); renderer.setSeriesPaint(0, Color.green); renderer.setSeriesPaint(1, Color.orange); } }The customize() method gets applied after the JFreeChart object is already created.
Then, the only thing one have to do is to take this JFreeChart object and modify its characteristics according to some more specific needs.
In the example above, two older series colors were replaced with new ones in the bar renderer, and so, the color scheme was altered for the Bar chart. Now, one have to tell to the JasperReports engine that a given chart should be customized using this customizer class. In the reports/BarChartReport.jrxml file
this class is set as chart customizer:
<barChart>
Note: When running the Charts sample, one can see that the Bar chart generated reports are the only with their items colored in green and orange. All the other generated reports are sharing another color scheme. |
|||||
|
|
© 2001-2010 Jaspersoft Corporation www.jaspersoft.com |