All hyperlink elements, like text fields, images, and charts, also expose an attribute
. Its purpose is to help customize the behavior of the specified
link when it is clicked in the viewer.
Currently, there are only two possible values for this attribute:
Self: The document to which the hyperlink points will be opened in the current
viewer window (
Blank: The document to which the hyperlink points will be opened in a new viewer
Parent: The document to which the hyperlink points will be opened in the parent
Top: The document to which the hyperlink points will be opened in the top frame
Custom target/Parameter name/Frame name: When the target value is not one of
the above-mentioned standard predefined target values, the target is either a custom
target that has to be processed by a registered target producer (see
Custom_Hyperlink_Target below), or it is the name of a hyperlink parameter that
gives the actual target value, or, if neither of the above apply, it is the name of the
frame in which the document will be opened (hyperlinkTarget="custom_target").
If the target is not specified, the default hyperlink target is
Custom Hyperlink Target
Sometimes, the hyperlink target is not known at report design time and has to be
specified dynamically at runtime, depending on the environment where the report runs.
In such cases, the value of the hyperlink target must be calculated based on some runtime
parameters or values. Targets defined at runtime are called custom hyperlink targets, as
opposed to the standard hyperlink targets.
Custom hyperlink targets are generated by hyperlink target producers, which are classes
that implement the net.sf.jasperreports.engine.export.JRHyperlinkTargetProducer
interface. Hyperlink target producers can be added to the JasperReports engine in a
transparent way, by registering instances of the
class as extensions. For more details about how to register JasperReports extensions, see
“Extensions Support” on page 280.
When the JasperReports engine encounters a custom target value specified in the target
attribute of a hyperlink, it first interrogates all registered hyperlink target producer
factories to obtain a target producer for this custom hyperlink. If no target producer is
found, the engine looks for any hyperlink parameter having the same name as the
specified custom target. If one is found, the engine takes its value as the true target to
use. If no parameter is found, the custom target value is considered a frame name into
which the hyperlink document must be opened.
The hyperlink element can have a ToolTip, which is controlled by the
<hyperlinkTooltipExpression> tag. The type of the expression should be
. The ToolTip expression will be evaluated along with the hyperlink
and the result will be saved in the generated document.
The built-in JasperReports viewer and the HTML exporter will honor the hyperlink
ToolTip and display it while the user views the report.
In addition to the standard hyperlink types, users can define hyperlinks having custom
types. A custom-typed hyperlink can have arbitrary parameters and is meant to be
processed by a hyperlink handler registered while exporting the report.
When a hyperlink is declared as having a type other than the built-in types, the hyperlink
is considered of custom type and the user is expected to provide handlers to process the
hyperlink when the report is exported.
Arbitrary hyperlink parameters can be added to a custom hyperlink using the
tag. These parameters are made available to the custom
hyperlink handler so that it can generate a final hyperlink depending on the parameter
Hyperlink parameter expressions are evaluated along with the hyperlink, and the results
are kept in the generated hyperlink object as parameter values.
When exporting the report to other formats such as HTML or PDF, the user can set a
factory of hyperlink handlers using the
parameter. A factory is an implementation of
, which is
responsible for creating a hyperlink handler for a custom hyperlink type. This hyperlink
handler created by the factory is a
instance, and it is
used for generating a hyperlink reference in the export document by assembling
hyperlink parameters and other information supplied at export time.
To handle custom hyperlinks in the built-in Swing viewer, you need to register a
hyperlink listener by calling
component. The listener is an
implementation of the
interface. When a report hyperlink gets clicked, the listener queries the hyperlink type
and performs the desired actions.
If present in a text field or image element declaration, the
tag transforms that particular text field or image into a local anchor of the resulting
document, to which hyperlinks can point. The anchor will bear the name returned after
evaluation of the anchor name expression, which should always return
Some of the document formats, such as PDF, have built-in support for tables of contents
and bookmarks. To allow you to make use of this, JasperReports lets you transform
anchors into document bookmarks. To be used as bookmarks, anchors should have an
indentation level set. To do this, set a positive integer value for the
attribute available for all hyperlink elements in JasperReports.
For more details about how to use hyperlink anchors as document bookmarks, see the
sample, which contains a table of contents when
exported to PDF format.
Report elements placed in any report section can be arranged in multiple nested groups.
The only reason for grouping your elements is to customize the stretch behavior of the
report elements, as explained at the beginning of this chapter.
One possible value of the
attribute, available for all report elements, is
. If you choose this option, the engine tries to identify the
object from the same group as the current graphic element that has suffered the biggest
amount of stretch. It will then adapt the height of the current report element to the height
of this tallest element of the group.
However, for this to work, you must group your elements. To do this, use the
tags to mark the elements that are part of the
Listing 10-15 gives the JRXML syntax for element groups.
Listing 10-15. JRXML Syntax
<!ELEMENT elementGroup (break | line | rectangle | ellipse | image
| textField | subreport | pieChart | pie3DChart | barChart |
bar3DChart | xyBarChart
| stackedBarChart | stackedBar3DChart | lineChart | xyLineChart |
| xyAreaChart | scatterChart | bubbleChart | timeSeriesChart |
| candlestickChart | meterChart | thermometerChart | multiAxisChart
| stackedAreaChart | elementGroup | crosstab | frame)*>
Element groups can contain other nested element groups, and there is no limit on the
number of the nested element groups.
Report sections are element groups themselves, so all report elements placed directly in a
containing band are part of the same default element group, which is the band itself. As
such, for these report elements,
have the same effect.
sample to see how element grouping works.
A frame is a report element that behaves like an element container. It is like a rectangle
that can contain other report elements. Frames can be nested into one another to any
Listing 10-16 gives the JRXML syntax for frames.
Listing 10-16. JRXML Syntax
<!ELEMENT frame (reportElement, box?, (break | line | rectangle |
ellipse | image
| staticText | textField | subreport | pieChart | pie3DChart |
barChart | bar3DChart
| xyBarChart | stackedBarChart | stackedBar3DChart| lineChart |
| areaChart | xyAreaChart | scatterChart | bubbleChart |
| highLowChart | candlestickChart | meterChart | thermometerChart
| multiAxisChart | stackedAreaChart | elementGroup | crosstab |
Frames have a background and a border, and they stretch to accommodate their content.
They are usually helpful when a common background and/or common border must be put
around a group of elements. The coordinates (
properties) and the
properties of an element placed inside a frame are all relative to the
frame, instead of the parent band.
A special break element was added to the list of elements that can be placed inside a
band. This is used for introducing a page break or column break at a specified position
within the band.
Listing 10-17 gives the JRXML syntax for page and column breaks.
Listing 10-17. JRXML Syntax
<!ELEMENT break (reportElement)>
type (Page | Column) "Page"
In many ways, this break element behaves like any other normal element placed in a band.
For instance, it can be conditionally displayed using
, and it can
float within the band if
is used. Other common element
properties like colors and styles do not make any sense for this kind of element, because it
behaves like an invisible horizontal line that crosses the whole parent band and indicates the
y position where a page break or column break should occur when the band content is
rendered during the report-filling process.
Whether a page break or a column break should be introduced is specified using the
attribute available for this element. By default, page breaks are created.
Generic report elements are like special placeholders that are put in the report template at
report design time, but are dealt with only at export time, when special content is
generated for them by the exporter.
A good example of a generic element use case is someone wanting to embed Flash
movies in reports exported to HTML format. JasperReports has built-in support for
displaying text and images, but there is no built-in element for displaying Flash movies.
This person would need to do the following to achieve it:
A new HTML export handler is developed, bundled into a JAR and deployed in the
application. The export handler would be registered with JasperReports for a
specific generic element type.
Optionally, a report custom component is implemented so that report designers
would be able to use specialized syntax in JRXMLs. The component
implementation would generate
at fill time.
Report designers would include either generic report elements or report
components (if implemented) in report templates.
At fill time, generic print elements whose type would match the type for which the
export handler was registered would be produced. Report expressions embedded in
the design report element are evaluated and the result is included in the produced
generic element as parameter values.
When the report will get exported to HTML, the custom HTML export handler will
output HTML snippets that embed Flash movies as part of the HTML output.
Generic element parameter values would be used to parametrize the resulting Flash
But generic elements can be placeholders for any kind of special content, not necessarily
Flash content. The generic element handler implementation has the freedom to generate
any kind of output that can be embedded in the exporter report.
Generic elements can be generated in filled reports either by a generic design element, or
by custom report components (see “Advanced JasperReports” on page 275 for more
details about custom components). Generic design elements can be used in simple
scenarios in which developing a specialized custom component would not benefit the
report design process. A generic design element consists of a generic element type, and a
list of element parameters.
A sample generic element is shown in the
that comes with the JasperReports project source files, where a special HTML snippet is
embedded into a report to show content coming from a public website.
Listing 10-18 gives the JRXML syntax for page and column breaks.
Listing 10-18. JRXML Syntax
<element ref="jr:genericElementParameter" minOccurs="0"
<attribute name="evaluationTime" use="optional" default="Now"
<attribute name="evaluationGroup" type="string"
Documents you may be interested
Documents you may be interested