Anchors, Bookmarks, and Hyperlinks

 

This section describes the creation of hyperlinks for most types of elements. For HTML5 charts, they are defined in a different way, as described in Hyperlinks in HTML5 Charts.

Image, textfield, and chart elements can be used both as anchors into a document and as hypertext links to external sources or other local anchors. JasperReports provides a powerful combination of settings to define hyperlinks. While a hyperlink usually opens a specific URL, JasperReports broadens the concept, extending it to a more complex object that can be used for more complicated functionality, such as executing a report in JasperReports to perform a drill-down or drill-up operation, pointing to a page within a PDF document, and so on.

 

To set anchor, bookmark, or hyperlink properties, go to the Hyperlink tab in the Properties view.

Anchor, Bookmark, and Hyperlink Properties

This window is divided in two sections:

Anchor and Bookmark
Hyperlink details

Use Anchor and Bookmark to create an anchor inside the current document; it is only available for elements that support hyperlinks (textfield, image, and chart). The name of the anchor is specified by means of an expression, and the bookmark level is used when the report is exported in PDF to create the Table of Content. Bookmarks can also be displayed in JasperReports Server when the report is displayed in the interactive viewer.

Note for developers:

In JasperReports 5.6 and later the same table of content is also available in the JasperPrint object, and can be explored by calling the method:

List<PrintBookmark> getBookmarks()

Anchors and Bookmarks

An anchor is a kind of label that identifies a specific position in a document. The Hyperlink tab includes a text area where you can enter an expression to be the name of the anchor. This name can be referenced by other links. Clicking the button opens the Expression Editor, in which you write or build the expression.

If you plan to export your report as a PDF, set a bookmark level to populate the bookmark tree, making the final document navigation much easier. To make an anchor available in a bookmark, simply choose a bookmark level higher than 1. Defining different levels creates nested bookmarks.

Overview of Hyperlink configuration

The definition of a hyperlink, given the number of options, may look a little bit cumbersome, but it is very simple in most of the use cases, in example if we really just want to link to an URL.

The Link Target allows to specify where the link should be open. This is probably the less important option, but since it is the first we encounter, it makes sense start from here (note: we may think to change its position, and move it at the bottom). The Link Target is very similar to the target attribute of an HTML anchor. The drop down box to set it, proposes the most common options (Self, Blank, Top, Parent), but it is still possible to manually specify a target name, which actually makes sense only when the hyperlink is used in a web environment (which is when the final export format is HTML like).

There are several type of hyperlink, and each of them can be used for different scopes. The built-in types provided by JasperReports are: Reference, Local Anchor, Local Page, Remote Anchor Remote Page. The first type, Reference, is the one used to create a typical URL link to some web address like http://www.jaspersoft.com/ and it is rendered in all the output formats supporting web link (include for instance Microsoft Excel and Word).

The other four are used to point to a position within the current or an external document, and primarily work in PDF and HTML.

Selecting a type, the user interface change accordingly to the information required by the type itself.

Please note the difference between URL parameters and hyperlink parameters. In the panel to configure a hyperlink there is a section called parameters. When working with a hyperlink of type Reference, these parameters are ignored: they don't have anything to do with the parameters that appear in a regular URL (in particular, the part of the URL following the question mark ). The URL should contain a parameter; you can use the Reference Expression. For example:

http://www.someurl.com/search?city=“ + $F{city} + “&country= “ + $F{country}

The values of the fields city and country are used to dynamically build a URL.

So why are these parameters interesting?Because they can be used by URL Handlers, especial JasperReports Library extensions, to manipulate and generate a hyperlinks.

The hyperlink type ReportExecution is one of these custom hyperlink extensions. It is used to execute a JasperReports Server report from another JasperReports Server report. This hyperlink type requires that the parameter _report is defined and points to the JasperReports Server report to execute. If this destination report contains one or more input controls, their value can be set by specifying the name of the input control as the parameter name and providing a value.

A ReportExecution hyperlink is configured in Jaspersoft Studio by simply dragging a report unit in the JasperReports Server repository explorer over an element that supports hyperlink (such as a textfield).

Dragging a report from the server into the Report Design

The auto configured hyperlink has the type set to ReportExecution and all the _report parameter set. Moreover, if the JasperReports Server Report has input controls, they are added to the list of parameters, ready to be populated with a proper value expression, as shown below.

Configuring Hyperlink Parameters

So, in general a hyperlink is defined by a type, one or more expressions (in case of Reference, just the Reference Expression that contains the URL to invoke), and zero or more parameters, depending by the type (in a regular Jaspersoft Studio installation, only the type ReportExecution does actually accept parameters).

Additionally, a hyperlink may also be completed with a ToolTip (by using the Tooltip Expression) and a visibility condition (Print When Expression) which can be used to prevent the link to be considered if the print when expression does not return the boolean value True (note that an empty print when expression is considered as True).

Hyperlink Types

Jaspersoft Studio provides six types of built-in hypertext links: Reference, LocalAnchor, LocalPage, RemoteAnchor and RemotePage. Other types of hyperlinks can be implemented and plugged into JasperReports.

The following table describes the hyperlink types:

Reference

The Reference link indicates an external source that is identified by a normal URL. This is ideal to point, for example, to a servility to manage a record drill-down tools. The only expression required is the hyperlink reference expression.

LocalAnchor

To point to a local anchor means to create a link between two locations into the same document. It can be used, for example, to link the titles of a summary to the chapters to which they refer.

To define the local anchor, specify a hyperlink anchor expression that produces a valid anchor name.

LocalPage

If instead of pointing to an anchor you want to point to a specific current report page, you need to create a LocalPage link. In this case, it is necessary to specify the page number you are pointing to by means of a hyperlink page expression (the expression has to return an Integer object)

RemoteAnchor

If you want to point to a particular anchor that resides in an external document, you use the RemoteAnchor link. In this case, the URL of the external file referenced must be specified in the Hyperlink Reference Expression field, and the name of the anchor must be specified in the Hyperlink Anchor Expression field.

RemotePage

This link allows you to point to a particular page of an external document. Similarly, in this case the URL of the external file pointed to must be specified in the Hyperlink Reference Expression field, and the page number must be specified by means of the hyperlink page expression. Some export formats have no support for hypertext links.

ReportExecution

This type of hyperlink is used to implement JasperReports Server’s drill-down feature.

Some export formats have no support for hypertext links.

Defining Hyperlinks

Some types of datasets let you assign a hyperlink to the value represented in the chart; in the report output, clicking the chart opens a web page or navigates to a different location in the report.

The click-enabled area depends on the chart type. For example, in pie charts, the hyperlink is linked to each slice of the pie; in bar charts, the click-enabled areas are the bars themselves.

Image, text field, and chart elements can be used both as anchors into a document and as hypertext links to external sources or local anchors.

To create hyperlinks:

1. Click the Hyperlink tab in the Properties view.
2. In the Link Target drop-down, choose one of the following target types:
     Self: This is the default setting. It opens the link in the current window.
     Blank: Opens the target in a new window. Used for output formats such as HTML and PDF.
     Top: Opens the target in the current window but outside eventually frames. Used for output formats such as HTML and PDF.
     Parent: Opens the target in the parent window (if available). Used for output formats such as HTML and PDF.
3. In the Link Type drop-down, choose whether the link type is None, Reference, LocalAnchor, LocalPage, RemoteAnchor, RemotePage, or ReportExecution.

See Hyperlink Types for an explanation of the different choices.

4. Click the button next to Hyperlink When Expression to create a tooltip for your hyperlink.
5. Save your report.

Hyperlink Parameters

Sometimes you need to define some parameters that must be attached to the link. The Link parameters table provides a convenient way to define them. The parameter value can be set using an expression. The parameter expression is supposed to be a string (since it is encoded in the URL). But when using custom link types it makes sense to set different types for parameters.

Hyperlink Tooltips

The tooltip expression is used to set a text to display as tooltip when the mouse is over the element that represents the hyperlink (this only works when the document is exported in a format that supports this type of interactive use).

Version: 
Feedback
randomness