net.sf.jasperreports.engine.JRHyperlink Maven / Gradle / Ivy
/*
* JasperReports - Free Java Reporting Library.
* Copyright (C) 2001 - 2023 Cloud Software Group, Inc. All rights reserved.
* http://www.jaspersoft.com
*
* Unless you have purchased a commercial license agreement from Jaspersoft,
* the following license terms apply:
*
* This program is part of JasperReports.
*
* JasperReports is free software: you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* JasperReports is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with JasperReports. If not, see 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 {@link #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> elementRemotePage - 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 {@link #getHyperlinkReferenceExpression()}<hyperlinkAnchorExpression> - see the related method {@link #getHyperlinkAnchorExpression()}<hyperlinkPageExpression> - see the related method {@link #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 {@link #getHyperlinkWhenExpression()}).
* Hyperlink Target
* All hyperlink elements, like textfields, images, and charts, also expose an attribute
* called hyperlinkTarget (see {@link #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 windowBlank - The document to which the hyperlink points will be opened in a new viewer
* windowParent - The document to which the hyperlink points will be opened in the parent
* frameTop - 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 {@link 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
* {@link net.sf.jasperreports.engine.export.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 {@link #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
* {@link net.sf.jasperreports.export.ReportExportConfiguration#getHyperlinkProducerFactory() getHyperlinkProducerFactory()}
* export configuration setting. A factory is an implementation of
* {@link net.sf.jasperreports.engine.export.JRHyperlinkProducerFactory}, which is
* responsible for creating a hyperlink handler for a custom hyperlink type. This hyperlink
* handler created by the factory is a
* {@link net.sf.jasperreports.engine.export.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
* {@link net.sf.jasperreports.swing.JRViewerPanel#addHyperlinkListener(net.sf.jasperreports.view.JRHyperlinkListener) addHyperlinkListener(JRHyperlinkListener)} on the
* {@link net.sf.jasperreports.swing.JRViewerPanel} component. The listener is an
* implementation of the {@link net.sf.jasperreports.view.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.
*
* @see net.sf.jasperreports.engine.JRAnchor
* @see net.sf.jasperreports.engine.export.JRHyperlinkProducer
* @see net.sf.jasperreports.engine.export.JRHyperlinkProducerFactory
* @see net.sf.jasperreports.engine.export.JRHyperlinkTargetProducer
* @see net.sf.jasperreports.engine.export.JRHyperlinkTargetProducerFactory
* @see net.sf.jasperreports.view.JRHyperlinkListener
* @author Teodor Danciu ([email protected])
*/
public interface JRHyperlink extends JRCloneable
{
/**
* Retrieves the hyperlink type for the element.
*
* The actual hyperlink type is determined by {@link #getLinkType() 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, {@link HyperlinkTypeEnum#CUSTOM CUSTOM} is returned.
*
* @return one of the hyperlink type constants
* @see #getLinkType()
*/
public HyperlinkTypeEnum getHyperlinkTypeValue();
/**
* @deprecated Replaced by {@link #getHyperlinkTargetValue()}.
*/
public byte getHyperlinkTarget();
/**
* Retrieves the hyperlink target for the element.
*
* The actual hyperlink target is determined by {@link #getLinkTarget() 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, {@link HyperlinkTargetEnum#CUSTOM} is returned.
*
* @return one of the hyperlink target constants
* @see #getLinkTarget()
*/
public HyperlinkTargetEnum getHyperlinkTargetValue();
/**
* Returns the expression whose value represents the hyperlink reference. It is only used when the hyperlink type is
* reference or anchor
*/
public JRExpression getHyperlinkReferenceExpression();
/**
* Returns the expression that is evaluated in order to decide if the hyperlink should be displayed. This
* expression always returns a boolean value.
*/
public JRExpression getHyperlinkWhenExpression();
/**
* Returns the expression whose value represents the anchor. It is only used when the hyperlink type is anchor.
*/
public JRExpression getHyperlinkAnchorExpression();
/**
* 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.
*/
public JRExpression getHyperlinkPageExpression();
/**
* 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.
*
* @return the hyperlink type
*/
public String getLinkType();
/**
* 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.
*
* @return the hyperlink target name
*/
public String getLinkTarget();
/**
* Returns the list of hyperlink parameters.
*
* The parameters can be used by custom hyperlink types to generate
* dynamic links.
*
* @return the list of hyperlink parameters
*/
public JRHyperlinkParameter[] getHyperlinkParameters();
/**
* Returns the expression which will generate the hyperlink tooltip.
*
* @return the expression which will generate the hyperlink tooltip
*/
public JRExpression getHyperlinkTooltipExpression();
}