Package net.sf.jasperreports.components
In addition to the standard report elements, such as text fields, images, charts, subreports and crosstabs JasperReports has an increasing number of core components that can be used to add content to generated reports. Some of them are used for greatly simplifying the creation of complex layouts, others are used to embed highly specialized visualization packages, such as barcodes and other types of graphics, or to generate report interactivity, like the Header Toolbar component.
The purpose of this feature is to allow users to extend the functionality of the JasperReports engine by plugging-in custom-made visual components that would take data as input and produce content that is embedded into the resulting documents. Custom made components can be anything from simple barcodes to tables, and professional charting packages.
The custom component support is relying on two other major features of the JasperReports library: extension support and generic elements and you need to be familiar with them before delving into custom components.
A custom component is a custom report element that has a defined structure and produces some output in generated reports, just like usual report elements do. Just like a normal chart element in a report template will produce an image element in the generated document, or just like a crosstab element present in the report template will produce a series of frames and text fields that makes up a tabular structure in the generated documents, generic custom components declared in a report template could generate any combination of simple elements and generic elements as the output of their built-in calculation and layout logic.
Custom components are supposed to come in bundles. A component bundle is a package comprising of one or several components that share the same XML namespace and schema. For example, a chart component bundle can contain multiple chart components, one for each type of chart (pie chart component, bar chart component and so on).
Custom Components Use Cases Examples
In the following use case example, we consider a JasperReports user that wants to replace the JFreeChart library (bundled with JasperReports by default for the built-in charting support) with some other charting package.Following are the few steps required to achieve it:
- A new component bundle is developed. The bundle can contain several components, that is, one per chart type.
- An XML schema for the chart components is designed.
- The schema uses a namespace reserved for the chart component implementation.
- A Java object model is designed for the chart components.
- Chart components can (optionally) use report subdatasets to produce data.
- The component implementation produces
JRPrintImage
instances when the report is filled. The images can use a custom image renderer (Renderable
) implementation. - The developed component code is bundled into a JAR and placed on the application's classpath.
- Report designers can now embed custom charts into JRXMLs.
Custom Component Implementation Overview
A typical implementation of a custom component would involve the following:- A
jasperreports_extension.properties
resource which registers an extension factory that reads a Spring beans file.
The Spring beans file that includes one or more beans of typeComponentsBundle
. Most of the time the default implementationDefaultComponentsBundle
is used. - A component bundle includes:
- A set of component types retrieved via
ComponentsBundle.getComponentTypes()
method
ComponentManager
implementations, usually instances of
DefaultComponentManager
. A
component manager is an entry point through which the handlers for a single
component type can be accessed. It contains:
- A component compiler
(
ComponentCompiler
implementation) that handles a component instance during report compile. It contains methods to collect report expressions from a component instance, to validate such a component and to create a component object that is included in the compiled report. - A component converter
(
ComponentDesignConverter
implementation) which onverts a component element into a print element that represents a preview of the component. - A factory of component fill instances,
ComponentFillFactory
implementation. - Such a factory would produce custom
FillComponent
instances. A fill component object is responsible for managing a component at fill time. A typical implementation would evaluate a set of expressions and use the results to create a print element to be included in the generated report.
To handle such generic elements at export time, custom generic element handler implementations need to be written
More specifically, the following classes would be extended by the component implementation:
JRDesignElementDataset
, for the report design/JRXML parsing stage.JRBaseElementDataset
, to be included in compiled reports.JRFillElementDataset
, to be used at fill time.
When implementing custom components, the most helpful information can be found in the form of JasperReports API Javadoc and samples. The following samples found in the /demo/samples folder of the JasperReports project distribution package show custom components:
Barbecue
: A sample that illustrates the use of the Barbecue component built into JasperReports.Barcode4j
: A sample that displays barcodes using the Barcode4j component built into JasperReports.xchartcomponent
: A chart component implementation that outputs axis charts generated by the XChart library (http://knowm.org/open-source/xchart/).
-
Interface Summary Interface Description BarcodeConstants -
Class Summary Class Description BaseElementHtmlHandler ComponentsExtensionsRegistryFactory Extension registry factory that includes built-in component element implementations.