Contains classes for built-in 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 type
ComponentsBundle
. Most of the
time the default implementation
DefaultComponentsBundle
is used.
- A component bundle includes:
- A XML parser object which implements
ComponentsXmlParser
. The
default
DefaultComponentXmlParser
implementation can be used in most cases. An XML parser provides:
- A namespace to be used for the component bundle.
- An XML schema to validate component XML fragments. The XML schema is
given as both a public location where it can be accessed, and as an internal
resource which will be used when parsing reports.
- A
XmlDigesterConfigurer
implementation which registers XML digester rules that are used to transform
at JRXML parse time component XML fragments into Java objects. In many
cases, new digester rule classes need to be written.
- One or more component managers,
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 XML writer
(
ComponentXmlWriter
implementation) which is responsible for producing a XML representation of
component instances.
- 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.
- If the component needs to generate an output elements that do not fall into the types
built into JasperReports (such as texts/images), the component can produce generic
print elements.
To handle such generic elements at export time, custom generic element handler
implementations need to be written
- If the component implementation generates charts, or, more generically, if it needs
to collect data from several records in the report dataset or from subdatasets, the
component object model will contain classes derived from abstract JasperReports
element dataset classes. These classes offer the infrastructure required to collect
data from report datasets.
More specifically, the following classes would be extended by the component
implementation:
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.
jchartscomponent
: A chart component implementation that outputs axis charts
generated by the jCharts library (http://jcharts.sf.net).
openflashchart
: A chart component that outputs Open Flash Charts in HTML
reports (http://teethgrinder.co.uk/open-flash-chart-2).