JasperReports Ultimate Guide - Sample Reference - Schema Reference - Configuration Reference - API (Javadoc)

JasperReports - Table of Contents Sample (version 6.4.3)


Shows how table-of-contents structures could be created for the generated reports.

Download All Sample Source Files
Browse Sample Source Files on Git


Main Features in This Sample

Creating Table-Of-Contents Structures


top

Creating Table-Of-Contents StructuresDocumented by Lucian Chirita


Description / Goal
How to create a table of contents with hyperlinks at the beginning of a document.

Since
6.0.0

Other Samples
/demo/samples/book


Table Of Contents - Overview

A Table of Contens part displays element bookmarks defined in the other report parts. The part report should have the net.sf.jasperreports.print.create.bookmarks set in order to collect bookmarks at report generation time.
The Table of Contents part needs to be evaluated after other report parts; if the part is to be printed at the beginning of the document it should have Report evaluation (and no subsequent parts should have the same evaluation).
Report bookmarks are fed into the Table of Contents part as a data source. The name of the data source parameter is provided via a part property called net.sf.jasperreports.bookmarks.data.source.parameter. If the part subreport directly uses the bookmarks as data source, the value of the property should be REPORT_DATA_SOURCE.
The bookmark data source provides the following fields:
	<field name="level" class="java.lang.Integer"/>
	<field name="label" class="java.lang.String"/>
	<field name="pageIndex" class="java.lang.Integer"/>
The part template needs to create Table of Contents entries based on these fields.
The level field can be used to indent Table of Contents entries.
The label fields provides the name of the bookmark and can be used to create a LocalAnchor hyperlink to the bookmark.
The pageIndex field is the temporary index of the page on which the bookmark is located. The page index is temporary because the pages generated by the Table of Contents part are not taken into account. When the table of contents is placed at the beginning of the document, the final page index can be displayed in the Table of Contents part by defining a text field with evaluationTime="Auto" that adds $V{PAGE_NUMBER} to $F{pageIndex}.
The following are generic text fields that display a bookmark label and a page reference for the bookmark:
  <textField hyperlinkType="LocalAnchor">
    <reportElement .../>
    <textFieldExpression>$F{label}</textFieldExpression>
    <hyperlinkAnchorExpression>$F{label}</hyperlinkAnchorExpression>
  </textField>
  <textField evaluationTime="Auto" hyperlinkType="LocalPage">
    <reportElement .../>
    <textFieldExpression>$V{PAGE_NUMBER} + $F{pageIndex} + 1</textFieldExpression>
    <hyperlinkPageExpression>$V{PAGE_NUMBER} + $F{pageIndex} + 1</hyperlinkPageExpression>
  </textField>
Table Of Contents - Examples

Below is an example of how to use report parts in order to create a document with Table of Contents.

In the main report (TableOfContentsReport.jrxml) one can see the sectionType="Part" attribute set, along with the net.sf.jasperreports.print.create.bookmarks property and two parts defined in the report:
<jasperReport 
  ... 
  sectionType="Part" 
  ...>
  <property name="net.sf.jasperreports.print.create.bookmarks" value="true"/>
  ...
  <group name="dummy">
    <groupExpression><![CDATA[1]] ></groupExpression>
    <groupHeader>
      <part evaluationTime="Report" uuid="1fadcc2f-31c1-49be-bd52-f8b69e38cd83">
        <property name="net.sf.jasperreports.bookmarks.data.source.parameter" value="REPORT_DATA_SOURCE"/>
        <partNameExpression><![CDATA["Table of Contents"]] ></partNameExpression>
        <p:subreportPart 
          xmlns:p="http://jasperreports.sourceforge.net/jasperreports/parts" 
          xsi:schemaLocation="http://jasperreports.sourceforge.net/jasperreports/parts http://jasperreports.sourceforge.net/xsd/parts.xsd" 
          usingCache="true">
          <subreportParameter name="ReportTitle">
            <subreportParameterExpression><![CDATA[$P{ReportTitle}]] ></subreportParameterExpression>
          </subreportParameter>
          <subreportExpression><![CDATA["TocPart.jasper"]] ></subreportExpression>
        </p:subreportPart>
      </part>
      <part uuid="3f63c482-39b2-43f1-a623-15fb046605a5">
        <partNameExpression><![CDATA["Countries"]] ></partNameExpression>
        <p:subreportPart 
          xmlns:p="http://jasperreports.sourceforge.net/jasperreports/parts" 
          xsi:schemaLocation="http://jasperreports.sourceforge.net/jasperreports/parts http://jasperreports.sourceforge.net/xsd/parts.xsd" 
          usingCache="true">
          <subreportParameter name="REPORT_CONNECTION">
            <subreportParameterExpression><![CDATA[$P{REPORT_CONNECTION}]] ></subreportParameterExpression>
          </subreportParameter>
          <subreportParameter name="ReportTitle">
            <subreportParameterExpression><![CDATA[$P{ReportTitle}]] ></subreportParameterExpression>
          </subreportParameter>
          <subreportExpression><![CDATA["TablePart.jasper"]] ></subreportExpression>
        </p:subreportPart>
      </part>
    </groupHeader>
  </group>
</jasperReport>
The first part in the report is the Table of Contents based on TocPart.jasper which can be obtained from the TocPart.jrxml file. One can see how the built-in data source containing necessary bookmark data is referred using a part property:

<property name="net.sf.jasperreports.bookmarks.data.source.parameter" value="REPORT_DATA_SOURCE"/>

The TocPart.jrxml report is a band-based report that declares 3 specific fields related to the built-in data source, and provides an appropriate design layout for the table of contents:
<jasperReport ...>
  ...
  <field name="level" class="java.lang.Integer"/>
  <field name="label" class="java.lang.String"/>
  <field name="pageIndex" class="java.lang.Integer"/>
  ...
  <title>
    <band ...>
      ...
    </band>
  </title>
  <pageHeader>
    <band ...>
      ...
    </band>
  </pageHeader>
  <detail>
    <band ...>
      ...
    </band>
  </detail>
</jasperReport>
The second part in the main report is based on TablePart.jasper which can be obtained from the TablePart.jrxml file. Here we have a table containing shipping orders from various customers, grouped by contries starting with the same letter. Bookmarks and bookmark levels are important in this report, because the table of content is built based on these bookmarks:
<jasperReport ...>
  ...
  <group name="FirstLetterGroup" minHeightToStartNewPage="60">
    <groupExpression><![CDATA[$V{FirstLetter}]] ></groupExpression>
    <groupHeader>
      <band height="25">
        ...
        <textField bookmarkLevel="1">
          <reportElement style="Sans_Bold" mode="Opaque" x="190" y="10" width="325" height="15" backcolor="#C0C0C0" uuid="f4a94c0c-fd87-4fa8-a56c-68f8f0345a65"/>
          <textFieldExpression><![CDATA[$V{FirstLetter}]] ></textFieldExpression>
          <anchorNameExpression><![CDATA["Letter " + $V{FirstLetter}]] ></anchorNameExpression>
        </textField>
      </band>
    </groupHeader>
  </group>
  <group name="ShipCountryGroup" minHeightToStartNewPage="60">
    <groupExpression><![CDATA[$F{ShipCountry}]] ></groupExpression>
    <groupHeader>
      <band height="20">
        ...
        <textField bookmarkLevel="2">
          <reportElement style="Sans_Bold" x="0" y="4" width="515" height="15" uuid="30ec046e-3560-4e5b-b03c-4f7b4c5851a5"/>
          <textFieldExpression>
            <![CDATA["  " + String.valueOf($V{ShipCountryNumber}) + ". " + String.valueOf($F{ShipCountry})]] >
          </textFieldExpression>
          <anchorNameExpression><![CDATA[$F{ShipCountry}]] ></anchorNameExpression>
        </textField>
      </band>
    </groupHeader>
    <groupFooter>
      ...
    </groupFooter>
  </group>
  <pageHeader>
    <band ...>
      ...
    </band>
  </pageHeader>
  <detail>
    <band ...>
      ...
    </band>
  </detail>
  <pageFooter>
    <band ...>
      ...
      <textField evaluationTime="Master">
        <reportElement x="0" y="20" width="515" height="15" uuid="c768ea70-8165-4afd-b13d-df34d5456803"/>
        <textElement textAlignment="Center"/>
        <textFieldExpression><![CDATA["Page " + $V{MASTER_CURRENT_PAGE} + " of " + $V{MASTER_TOTAL_PAGES}]] ></textFieldExpression>
      </textField>
    </band>
  </pageFooter>
</jasperReport>
One can see also an example of special MASTER_CURRENT_PAGE and MASTER_TOTAL_PAGES variables usage, along with the new evaluationTime type Master. 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/hsqldb within the JasperReports source project and run the > ant runServer command. It will start the HSQLDB server shipped with the JasperReports distribution package. Let this terminal running the HSQLDB server.
Open a new command prompt/terminal window and set the current folder to demo/samples/tableofcontents 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/tableofcontents/build/reports directory.
Then the report will open in the JasperReports internal viewer.



© 2001- TIBCO Software Inc. www.jaspersoft.com