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

<sample>

  <name>book</name>
  <title>Report Parts Sample</title>
  <description>Shows how report parts can be used.</description>

  <mainFeature ref="parts"/>
  <secondaryFeature name="tableofcontents" sample="tableofcontents" title="Creating Table-Of-Contents Structures"/>
  
  <!-- parts -->
  
  <feature name="parts" title="Report Parts (Book Reports)">
    <description>
On report parts.
    </description>
    <since>6.0.0</since>
    <documentedBy>
      <author>
    	<name>Lucian Chirita</name>
    	<email>lchirita@users.sourceforge.net</email>
      </author>
    </documentedBy>
  	<otherSample ref="tableofcontents"/>
    <content>

<b>What is a report part</b>
<br/>
A report part is similar to a subreport, the difference being that pages generated by parts are directly included in the generated report,
while subreport pages are embedded into the pages of the parent report.
<br/>
Report parts are not report elements and are not placed on bands, but used instead of bands inside report sections.
Parts and bands cannot be mixed in the same report; reports that consist of parts need to have the <code>sectionType</code> attribute set to <code>Part</code>.
We are going to refer to reports that contain parts as part reports.
Part reports can be nested, that is a part of a report can be a part report itself.
<br/>
All report section (the detail, group header and group footer sections) can contain one or several parts.
The report dataset determines how many times each part is instantiated, for example a part placed on the detail section will be printed for each record from the dataset.
Dummy groups (that is groups that have constant group expressions) can be used to introduce parts that should only be included once in the generated document.
<br/>
Each part has its own page size, therefore a document obtained from a part report can contain pages of different dimensions.

<br/>
<br/>
<b>General part configuration</b>
<br/>
Each part can define a name expression, a print when expression, an evaluation time and additional generic properties.
<br/>
The following fragment in JRXML illustrates how a part looks like:
<pre><![CDATA[
  <part evaluationTime="Group" evaluationGroup="DatasetGroup">
    <property name="custom.property" value="custom_value"/>
    <printWhenExpression>...</printWhenExpression>
    <partNameExpression>"A report part"</partNameExpression>
    <p:subreportPart ...>
      ...
    </p:subreportPart>
  </part>
]]></pre>
<br/>
The print when expression is evaluate in order to determine whether the part is to be printed.
<br/>
The name expression provides a user visible name for the part.  If the name expression is not defined, the name of the subreport is used.
Certain report viewers (such as the JasperReports Swing viewer and the JasperReports Server report viewer) will display tabs for documents generated from part reports.
Each part in the report is shown as a tab, and the part name is used as tab label.
<br/>
The optional evaluation time attributes determine the moment at which the part is evaluated and filled.
Parts with delayed evaluation are inserted at their original position in the document, you can have a report that has a first part evaluated after all subsequent parts. 
<br/>
A delayed evaluation can be achieved by setting the <code>evaluationTime</code> attribute to <code>Report</code> or <code>Group</code>; in the latter case the <code>evaluationGroup</code> needs to be present.
If the attributes are not present, the part is evaluated immediately.
<br/>
Group evaluated parts are printed when a group of the report dataset breaks and when the report dataset ends.
Report evaluated parts are evaluated after iterating the report dataset and after printing all parts with immediate or group evaluation.

<br/>
<br/>
<b>Subreport parts</b>
<br/>
JasperReports contains a report part infrastructure that makes use of pluggable part component implementations.
A part component is assumed to produce pages that are included in the generated document.
<br/>
The only part implementation currently built into JasperReports uses on a report templates to generate pages.
Such a part is called a subreport part.
<br/>
A subreport part has the following structure in JRXML:
<pre><![CDATA[
  <part>
    <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">
      <parametersMapExpression>...</parametersMapExpression>
      <subreportParameter name="SubreportParameter1">
        <subreportParameterExpression>...</subreportParameterExpression>
      </subreportParameter>
      <subreportParameter name="SubreportParameter2">
        <subreportParameterExpression>...</subreportParameterExpression>
      </subreportParameter>
      <subreportExpression>"ReportPart.jasper"</subreportExpression>
      <returnValue subreportVariable="SubreportVariable" toVariable="ParentVariable" calculation="Nothing"/>
    </p:subreportPart>
  </part>
]]></pre>

The semantics of the elements is equivalent to that of subreport elements.
One difference from subreport elements is that there are no explicit <code>dataSourceExpression</code> and <code>connectionExpression</code> elements.
One can send a data source or a JDBC connection to a subreport part by defining a <code>subreportParameter</code> that uses <code>REPORT_DATA_SOURCE</code> or <code>REPORT_CONNECTION</code> as parameter name.

<br/>
<br/>
<b>Master page variables</b>
<br/>
The preexisting <code>PAGE_NUMBER</code> variable has a scope limited to the lifecycle of the subreport, and it can only be used to print the index of the page in the subreport and the number of pages generated by the subreport part.
<br/>
Two new variables have been introduced to allow subreport parts to print the index of the current page in the generated document and the total number of pages in the document.
The variables are named <code>MASTER_CURRENT_PAGE</code> and <code>MASTER_TOTAL_PAGES</code> and should only be used in text fields that have <code>evaluationTime=&quot;Master&quot;</code> or <code>evaluationTime=&quot;Auto&quot;</code> because they evaluate to null in all other contexts.
<br/>
A typical text field using the two variables would look something like the following:
<pre><![CDATA[
  <textField evaluationTime="Master">
    <reportElement .../>
    <textFieldExpression>"Page " + $V{MASTER_CURRENT_PAGE} + " of " + $V{MASTER_TOTAL_PAGES}</textFieldExpression>
  </textField>
]]></pre>

<br/>
<br/>
<b>Table of Contents</b>
<br/>
<br/>
Special provisions are available for designing a report part that will show a Table of Contents of the generate document.
<a href="../tableofcontents/index.html">Here</a> is an example of how to create a table of contents with report's hyperlinks at the beginning of a document.

    </content>
  </feature>

</sample>
