net.sf.jasperreports.engine

Interface JRHyperlink

All Superinterfaces:

Cloneable, JRCloneable

All Known Subinterfaces:

ChartSettings, JRChart, JRImage, JRTextField

All Known Implementing Classes:

FillChartSettings, JRBaseChart, JRBaseHyperlink, JRBaseImage, JRBaseTextField, JRDesignChart, JRDesignHyperlink, JRDesignImage, JRDesignTextField, JRFillChart, JRFillImage, JRFillTextField, StandardChartSettings

public interface JRHyperlink
extends JRCloneable

An interface providing hyperlink functionality. It must be implemented by elements that can contain hyperlinks.

Hyperlinks

JasperReports allows users to create drill-down reports, which introduce tables of contents in generated 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 below.

Hyperlink Type

The hyperlinkType attribute (see getHyperlinkTypeValue()) attribute can hold any text value, but by default, the engine recognizes the following standard hyperlink types:

• None - By default, neither the text fields nor the images represent hyperlinks, even if the special hyperlink expressions are present.
• Reference - The current hyperlink points to an external resource specified by the corresponding <hyperlinkReferenceExpression> element, usually a URL.
• LocalAnchor - The current hyperlink points to a local anchor specified by the corresponding <hyperlinkAnchorExpression> tag.
• LocalPage - The current hyperlink points to a one-based page index within the current document specified by the corresponding <hyperlinkPageExpression> element.
• RemoteAnchor - The current hyperlink points to an anchor specified by the <hyperlinkAnchorExpression> element within an external document indicated by the corresponding <hyperlinkReferenceExpression> element
• RemotePage - The current hyperlink points to a one-based page index specified by the <hyperlinkPageExpression> element, within an external document indicated by the corresponding <hyperlinkReferenceExpression> element

Any hyperlinkType value not in the preceding list is considered a custom hyperlink type. More details about those are given in the "Custom Hyperlinks" section, which follows.

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> - see the related method getHyperlinkReferenceExpression()
• <hyperlinkAnchorExpression> - see the related method getHyperlinkAnchorExpression()
• <hyperlinkPageExpression> - see the related method getHyperlinkPageExpression()

Note that the first two should always return java.lang.String and the third should return java.lang.Integer values.

There are situations when hyperlinks should be displayed only if a certain condition is met. In such cases one can use the Boolean expression <hyperlinkWhenExpression> (see getHyperlinkWhenExpression()).

Hyperlink Target

All hyperlink elements, like textfields, images, and charts, also expose an attribute called hyperlinkTarget (see getHyperlinkTarget()). Its purpose is to help customize the behavior of the specified link when it is clicked in the viewer.

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 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.

If the target is not specified, the default hyperlink target is Self.

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 (see getHyperlinkTooltipExpression()). 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 getHyperlinkProducerFactory() export configuration 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, one needs to register a hyperlink listener by calling addHyperlinkListener(JRHyperlinkListener) on the JRViewerPanel 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.

Author:

Teodor Danciu ([email protected])

See Also:

JRAnchor, JRHyperlinkProducer, JRHyperlinkProducerFactory, JRHyperlinkTargetProducer, JRHyperlinkTargetProducerFactory, JRHyperlinkListener

Method Summary

Modifier and Type	Method and Description
JRExpression	getHyperlinkAnchorExpression() Returns the expression whose value represents the anchor.
JRExpression	getHyperlinkPageExpression() Returns an integer representing the page index of the link.
JRHyperlinkParameter[]	getHyperlinkParameters() Returns the list of hyperlink parameters.
JRExpression	getHyperlinkReferenceExpression() Returns the expression whose value represents the hyperlink reference.
byte	getHyperlinkTarget() Retrieves the hyperlink target for the element.
JRExpression	getHyperlinkTooltipExpression() Returns the expression which will generate the hyperlink tooltip.
HyperlinkTypeEnum	getHyperlinkTypeValue() Retrieves the hyperlink type for the element.
JRExpression	getHyperlinkWhenExpression() Returns the expression that is evaluated in order to decide if the hyperlink should be displayed.
String	getLinkTarget() Returns the hyperlink target name.
String	getLinkType() Returns the hyperlink type.

Methods inherited from interface net.sf.jasperreports.engine.JRCloneable

clone

Method Detail

getHyperlinkTypeValue

HyperlinkTypeEnum getHyperlinkTypeValue()

Retrieves the hyperlink type for the element.

The actual hyperlink type is determined by getLinkType(). This method can is used to determine whether the hyperlink type is one of the built-in types or a custom type. When hyperlink is of custom type, CUSTOM is returned.

Returns:

one of the hyperlink type constants

See Also:

getLinkType()

getHyperlinkTarget

byte getHyperlinkTarget()

Retrieves the hyperlink target for the element.

The actual hyperlink target is determined by getLinkTarget(). This method can is used to determine whether the hyperlink target is one of the built-in target names or a custom one. When hyperlink has a custom target name, HyperlinkTargetEnum.CUSTOM is returned.

Returns:

one of the hyperlink target constants

See Also:

getLinkTarget()

getHyperlinkReferenceExpression

JRExpression getHyperlinkReferenceExpression()

Returns the expression whose value represents the hyperlink reference. It is only used when the hyperlink type is reference or anchor

getHyperlinkWhenExpression

JRExpression getHyperlinkWhenExpression()

Returns the expression that is evaluated in order to decide if the hyperlink should be displayed. This expression always returns a boolean value.

getHyperlinkAnchorExpression

JRExpression getHyperlinkAnchorExpression()

Returns the expression whose value represents the anchor. It is only used when the hyperlink type is anchor.

getHyperlinkPageExpression

JRExpression getHyperlinkPageExpression()

Returns an integer representing the page index of the link. It is only used when the hyperlink type is page. If the expression does not evaluate to an integer, an exception will be thrown.

getLinkType

String getLinkType()

Returns the hyperlink type.

The type can be one of the built-in types (Reference, LocalAnchor, LocalPage, RemoteAnchor, RemotePage), or can be an arbitrary type.

Returns:

the hyperlink type

getLinkTarget

String getLinkTarget()

Returns the hyperlink target name.

The type can be one of the built-in names (Self, Blank, Top, Parent), or can be an arbitrary name.

Returns:

the hyperlink target name

getHyperlinkParameters

JRHyperlinkParameter[] getHyperlinkParameters()

Returns the list of hyperlink parameters.

The parameters can be used by custom hyperlink types to generate dynamic links.

Returns:

the list of hyperlink parameters

getHyperlinkTooltipExpression

JRExpression getHyperlinkTooltipExpression()

Returns the expression which will generate the hyperlink tooltip.

Returns:

the expression which will generate the hyperlink tooltip