<?xml version="1.0" encoding="UTF-8"?>

<sample>

  <name>tableofcontents</name>
  <title>Table of Contents Sample</title>
  <description>Shows how table-of-contents structures could be created for the generated reports.</description>

  <mainFeature ref="tableofcontents"/>
  
  <!-- tableofcontents -->
  
  <feature name="tableofcontents" title="Creating Table-Of-Contents Structures">
    <description>
How to create a table of contents with hyperlinks at the beginning of a document.
    </description>
    <since>6.0.0</since>
    <documentedBy>
      <author>
    	<name>Lucian Chirita</name>
    	<email>lchirita@users.sourceforge.net</email>
      </author>
    </documentedBy>
  	<otherSample ref="book"/>
    <content>
<subtitle name="overview">Table Of Contents - Overview</subtitle>
<br/>
<br/>
A Table of Contens part displays element bookmarks defined in the other report parts.
The part report should have the <code>net.sf.jasperreports.print.create.bookmarks</code> set in order to collect bookmarks at report generation time.
<br/>
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 <code>Report</code> evaluation (and no subsequent parts should have the same evaluation).
<br/>
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 <code>net.sf.jasperreports.bookmarks.data.source.parameter</code>.
If the part subreport directly uses the bookmarks as data source, the value of the property should be <code>REPORT_DATA_SOURCE</code>.
<br/>
The bookmark data source provides the following fields:
<pre><![CDATA[
	<field name="level" class="java.lang.Integer"/>
	<field name="label" class="java.lang.String"/>
	<field name="pageIndex" class="java.lang.Integer"/>
]]></pre>

The part template needs to create Table of Contents entries based on these fields.
<br/>
The <code>level</code> field can be used to indent Table of Contents entries.
<br/>
The <code>label</code> fields provides the name of the bookmark and can be used to create a <code>LocalAnchor</code> hyperlink to the bookmark.
<br/>
The <code>pageIndex</code> 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 <code>evaluationTime=&quot;Auto&quot;</code> that adds <code>$V{PAGE_NUMBER}</code> to <code>$F{pageIndex}</code>.
<br/>
The following are generic text fields that display a bookmark label and a page reference for the bookmark:
<pre><![CDATA[
  <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>
]]></pre>
<subtitle name="examples">Table Of Contents - Examples</subtitle>
<br/>
<br/>
Below is an example of how to use report parts in order to create a document with Table of Contents.
<br/>
<br/>
In the main report (<code>TableOfContentsReport.jrxml</code>) one can see the <code>sectionType="Part"</code> attribute set, along with the 
<code>net.sf.jasperreports.print.create.bookmarks</code> property and two parts defined in the report:
<pre><![CDATA[
<jasperReport 
  ... 
  sectionType="Part" 
  ...>
  <property name="net.sf.jasperreports.print.create.bookmarks" value="true"/>
  ...
  <group name="dummy">
    <groupExpression>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>
]]></pre>
The first part in the report is the Table of Contents based on <code>TocPart.jasper</code> which can be obtained from the <code>TocPart.jrxml</code> file. 
One can see how the built-in data source containing necessary bookmark data is referred using a part property:
<br/>  
<br/>  
<code>&lt;property name="net.sf.jasperreports.bookmarks.data.source.parameter" value="REPORT_DATA_SOURCE"/&gt;</code>
<br/>
<br/>
The <code>TocPart.jrxml</code> 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:
<pre><![CDATA[
<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>
]]></pre>
The second part in the main report is based on <code>TablePart.jasper</code> which can be obtained from the <code>TablePart.jrxml</code> 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:
<pre><![CDATA[
<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>
]]></pre>
One can see also an example of special <code>MASTER_CURRENT_PAGE</code> and <code>MASTER_TOTAL_PAGES</code> variables usage, 
along with the new <code>evaluationTime</code> type <code>Master</code>.
<b>Running the Sample</b>
<br/>
<br/>
Running the sample requires the <a href="http://ant.apache.org/">Apache Ant</a> library. Make sure that <code>ant</code> is already installed on your system (version 1.5 or later).
<br/>
In a command prompt/terminal window set the current folder to <code>demo/hsqldb</code> within the JasperReports source project and run the <code>&gt; ant runServer</code> command. 
It will start the HSQLDB server shipped with the JasperReports distribution package. Let this terminal running the HSQLDB server.  
<br/>
Open a new command prompt/terminal window and set the current folder to <code>demo/samples/tableofcontents</code> within the JasperReports source project and run the <code>&gt; ant test view</code> command.
<br/>
It will generate all supported document types containing the sample report in the <code>demo/samples/tableofcontents/build/reports</code> directory. 
<br/>
Then the report will open in the JasperReports internal viewer.

    </content>
  </feature>
</sample>
