net.sf.jasperreports.engine

## Interface JRHyperlink

- All Superinterfaces:
    java.lang.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(listener)` on the `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.
  Version:
    $Id: JRHyperlink.java 7050 2014-04-25 11:09:07Z shertage $
  Author:
    Teodor Danciu (teodord@users.sourceforge.net)
  See Also:
    `JRAnchor`, `JRHyperlinkProducer`, `JRHyperlinkProducerFactory`, `JRHyperlinkTargetProducer`, `JRHyperlinkTargetProducerFactory`, `JRHyperlinkListener`

- - ### Method Summary

    Methods
    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.
    `byte` | `getHyperlinkType()` Deprecated. Replaced by `getHyperlinkTypeValue()`.
    `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.
    `java.lang.String` | `getLinkTarget()` Returns the hyperlink target name.
    `java.lang.String` | `getLinkType()` Returns the hyperlink type.

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

      `clone`

- - ### Method Detail

    - #### getHyperlinkType

          byte getHyperlinkType()

      Deprecated. Replaced by `getHyperlinkTypeValue()`.

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

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

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

© 2001-2010 Jaspersoft Corporation www.jaspersoft.com