Hyperlinks, Anchors and Bookmarks
JasperReports allows you to create drill-down reports, which introduce tables of contents
in your documents or redirect viewers to external documents using special report elements called hyperlinks.
When the user clicks a hyperlink, he or she is redirected to a local destination within the
current document or to an external resource. Hyperlinks are not the only actors in this
viewer-redirecting scenario. You also need a way to specify the possible hyperlink
destinations in a document. These local destinations are called anchors.
There are no special report elements that introduce hyperlinks or anchors in a report
template, but rather special settings that make a usual report element a hyperlink and/or an anchor.
In JasperReports, only text field, image, and chart elements can be hyperlinks or anchors.
This is because all these types of elements offer special settings that allow you to specify
the hyperlink reference to which the hyperlink will point to or the name of the local
anchor. Note that a particular text field or image can be both anchor and hyperlink at the
same time.
There are five standard types of hyperlinks supported by JasperReports by default. These
are described in the following subsections.
Hyperlink Type
The type of the hyperlink is stored in an attribute named hyperlinkType. This attribute can hold any text value, but by default, the engine recognizes
the following standard hyperlink types:
None - the text field or the image does not represent a hyperlink. This is considered the default behavior.Reference - the current hyperlink points to an external resource.LocalAnchor - the current hyperlink points to a local anchor.LocalPage - the current hyperlink points to a one-based page index within the current document.RemoteAnchor - the current hyperlink points to an anchor within an external document.RemotePage - the current hyperlink points to a one-based page index within an external document.
Hyperlink Expressions
Depending on the standard hyperlink type specified, one or two of the following
expressions are evaluated and used to build the reference to which the hyperlink element
will point:
<hyperlinkReferenceExpression>
<hyperlinkAnchorExpression>
<hyperlinkPageExpression>
Note that the first two should always return java.lang.String and the third should return java.lang.Integer values.
A remote anchor requires both <hyperlinkReferenceExpression> and <hyperlinkAnchorExpression> to be present.
A remote page requires both <hyperlinkReferenceExpression> and <hyperlinkPageExpression> to be present.
Hyperlink Target
All hyperlink elements, like text fields, images, and charts, also expose an attribute
called hyperlinkTarget. Its purpose is to help customize the behavior of the specified
link when it is clicked in the viewer.
Currently, there are only four possible values for this attribute:
Self - the document to which the hyperlink points will be opened in the current viewer window. This is the default behavior.Blank - the document to which the hyperlink points will be opened in a new viewer window.Parent - the document to which the hyperlink points will be opened in the parent frame.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, 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").
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 JRHyperlinkTargetProducer
interface. Hyperlink target producers can be added to the JasperReports engine in a
transparent way, by registering instances of the
JRHyperlinkTargetProducerFactory
class as extensions.
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.
Hyperlink ToolTips
The hyperlink element can have a ToolTip, which is controlled by the
<hyperlinkTooltipExpression> tag. The type of the expression should be
java.lang.String. 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.
Custom Hyperlinks
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
<hyperlinkParameter> tag. These parameters are made available to the custom
hyperlink handler so that it can generate a final hyperlink depending on the parameter
values.
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 obtain a
factory of hyperlink handlers using the getHyperlinkProducerFactory() exporter
setting. A factory is an implementation of
JRHyperlinkProducerFactory, which is
responsible for creating a hyperlink handler for a custom hyperlink type. This hyperlink
handler created by the factory is a
JRHyperlinkProducer 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 addHyperlinkListener(listener) on the
net.sf.jasperreports.view.JRViewer component. The listener is an
implementation of the JRHyperlinkListener
interface. When a report hyperlink gets clicked, the listener queries the hyperlink type
and performs the desired actions.
Anchors
If present in a text field or image element declaration, the <anchorNameExpression>
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
java.lang.String values.
Bookmarks
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 bookmarkLevel
attribute available for all hyperlink elements in JasperReports.
Creating a Local Anchor Example
"This is the TITLE section"
"title"
]]>
The <anchorNameExpression> tag was used here in order to associate a local anchor, named title, with this text field.
Creating a Local Anchor Hyperlink Example
" >> Click here to go to the title section."
"title"
]]>
The hyperlink created using the <hyperlinkAnchorExpression> tag points to the local anchor created above.
Creating a Local Page Hyperlink Example
" >> Click here to go to the second page."
Integer.valueOf(2)
]]>
The hyperlink created using the <hyperlinkPageExpression> tag points to the second page of the current document.
Creating a Reference Hyperlink Example
" >> Click here to go to www.google.com"
"http://www.google.com"
]]>
The hyperlink created using the <hyperlinkReferenceExpression> tag points to the www.google.com site.
Creating a Remote Anchor Hyperlink Example
" >> Click here to go to another PDF file (in fact, we use the same file)."
"./HyperlinkReport.pdf"
"title"
]]>
The hyperlink created using the <hyperlinkReferenceExpression> and <hyperlinkAnchorExpression> tags points to an anchor named title found in the HyperlinkReport.pdf document, saved in the current directory.
Creating a Remote Page Hyperlink Example
" >> Click here to go to another PDF file (in fact, we use the same file)."
"./HyperlinkReport.pdf"
Integer.valueOf(2)
]]>
The hyperlink created using the <hyperlinkReferenceExpression> and <hyperlinkPageExpression> tags points to the second page of the HyperlinkReport.pdf document, saved in the current directory.
Running the Sample
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/samples/hyperlink 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/hyperlink/build/reports directory.
Then the report will open in the JasperReports internal viewer.