Sample Reference - Schema Reference - Configuration Reference - API (Javadoc)
JasperReports - Hyperlink Sample (version 4.0.1)

Shows how hyperlinks and anchors could be used in report templates.

Download All Sample Source Files
Browse Sample Source Files on SVN


Main Features in This Sample

Hyperlinks

Generating the JRXML Source File for an In-Memory Report Report Template Object

Creating Watermarks and Page Backgrounds


top
HyperlinksDocumented by Sanda Zaharia


Description / Goal
How to use hyperlinks and anchors for text elements and image elements.

Since
0.3.2


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 set a factory of hyperlink handlers using the HYPERLINK_PRODUCER_FACTORY export parameter. 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 
<textField>
  <reportElement x="5" y="5" width="450" height="20"/>
  <textElement>
    <font size="14" isBold="true"/>
  </textElement>
  <textFieldExpression class="java.lang.String">"This is the TITLE section"</textFieldExpression>
  <anchorNameExpression>"title"</anchorNameExpression>
</textField>
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 
<textField hyperlinkType="LocalAnchor">
  <reportElement x="5" y="35" width="300" height="15" forecolor="#FF0000"/>
  <textFieldExpression class="java.lang.String">"  >> Click here to go to the title section."</textFieldExpression>
  <hyperlinkAnchorExpression>"title"</hyperlinkAnchorExpression>
</textField>
The hyperlink created using the <hyperlinkAnchorExpression> tag points to the local anchor created above.

Creating a Local Page Hyperlink Example 
<textField hyperlinkType="LocalPage">
  <reportElement x="5" y="65" width="300" height="15" forecolor="#008000"/>
  <textFieldExpression class="java.lang.String">"  >> Click here to go to the second page."</textFieldExpression>
  <hyperlinkPageExpression>Integer.valueOf(2)</hyperlinkPageExpression>
</textField>
The hyperlink created using the <hyperlinkPageExpression> tag points to the second page of the current document.

Creating a Reference Hyperlink Example 
<textField hyperlinkType="Reference">
  <reportElement x="5" y="95" width="300" height="15"/>
  <textFieldExpression class="java.lang.String">"  >> Click here to go to www.google.com"</textFieldExpression>
  <hyperlinkReferenceExpression>"http://www.google.com"</hyperlinkReferenceExpression>
</textField>
The hyperlink created using the <hyperlinkReferenceExpression> tag points to the www.google.com site.

Creating a Remote Anchor Hyperlink Example 
<textField hyperlinkType="RemoteAnchor">
  <reportElement x="5" y="125" width="350" height="15"/>
  <textFieldExpression class="java.lang.String">"  >> Click here to go to another PDF file (in fact, we use the same file)."</textFieldExpression>
  <hyperlinkReferenceExpression>"./HyperlinkReport.pdf"</hyperlinkReferenceExpression>
  <hyperlinkAnchorExpression>"title"</hyperlinkAnchorExpression>
</textField>
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 
<textField hyperlinkType="RemoteAnchor">
  <reportElement x="5" y="125" width="350" height="15"/>
  <textFieldExpression class="java.lang.String">"  >> Click here to go to another PDF file (in fact, we use the same file)."</textFieldExpression>
  <hyperlinkReferenceExpression>"./HyperlinkReport.pdf"</hyperlinkReferenceExpression>
  <hyperlinkPageExpression>Integer.valueOf(2)</hyperlinkPageExpression>
</textField>
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.

top
Generating the JRXML Source File for an In-Memory Report Report Template Object


Description / Goal
How to generate the JRXML representation of an in-memory report template object.

Since
0.3.2

Other Samples
/demo/samples/noxmldesign
/demo/samples/antcompile


[Under Construction]

top
Creating Watermarks and Page Backgrounds


Description / Goal
How to generate a watermark image in a document.

Since
0.4.6


The Background Section

Digital watermarking is a very useful feature having a wide range of applications related to copyright protection, source tracking, etc. It consists in embedding a specific information into a digital signal, so that it's quite difficult to be removed. The signal may be any kind of document, picture, audio, pictures or video, for example. When the signal gets copied, this additional information is copied too.
A simple way to add watermark info to a given document is to embed an image into document's pages' background. If elements present on the page are set with a certain transparency percent, then the background image becomes visible under page elements, and it's difficult to be removed when the document gets copied.
In order to handle page backgrounds, there is a special section in JasperReports that is rendered on all pages and its content cannot overflow to the next page. This is the background section. Normal report sections are rendered one after the other, but the background section does not interfere with the other report sections and can be used to achieve watermark effects or to create the same background for all pages. Elements placed on this section are evaluated at page initialization time and are displayed in the back. All other page elements are displayed on top of the background elements.

Using the Background Section Example

Below is an example of how to embed an image into document's page background. The image is loaded from the jr.watermark.gif file placed in the current directory. 
<background>
  <band height="742">
    <image scaleImage="Clip" vAlign="Bottom">
      <reportElement x="0" y="0" width="150" height="742"/>
      <imageExpression class="java.lang.String">"jr.watermark.gif"</imageExpression>
    </image>
  </band>
</background>


© 2001-2010 Jaspersoft Corporation www.jaspersoft.com