JasperReports - Report Parts Sample

Report Parts (Book Reports)

Secondary Features

Creating Table-Of-Contents Structures

Report Parts (Book Reports)

Description / Goal
On report parts.

Since: 6.0.0

Other Samples
/demo/samples/tableofcontents

What is a report part

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.
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 sectionType attribute set to Part. 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.
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.
Each part has its own page size, therefore a document obtained from a part report can contain pages of different dimensions.

General part configuration

Each part can define a name expression, a print when expression, an evaluation time and additional generic properties.
The following fragment in JRXML illustrates how a part looks like:

<part evaluationTime="Group" evaluationGroup="DatasetGroup">
  <property name="custom.property" value="custom_value"/>
  <printWhenExpression>...</printWhenExpression>
  <partNameExpression>"A report part"</partNameExpression>
  <component kind="subreportPart">
    ...
  </component>
</part>

The print when expression is evaluate in order to determine whether the part is to be printed. 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.
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.
A delayed evaluation can be achieved by setting the evaluationTime attribute to Report or Group; in the latter case the evaluationGroup needs to be present. If the attributes are not present, the part is evaluated immediately.
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.

Subreport parts

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.
The only part implementation currently built into JasperReports uses on a report templates to generate pages. Such a part is called a subreport part.
A subreport part has the following structure in JRXML:

<part>
  <partNameExpression><![CDATA["ReportPart1"]] ></partNameExpression>
  <component kind="subreportPart" usingCache="true">
    <expression><![CDATA["ReportPart1.jasper"]] ></expression>
    <parameter name="REPORT_CONNECTION">
      <expression><![CDATA[$P{REPORT_CONNECTION}]] ></expression>
    </parameter>
  </component>
</part>

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

Master page variables

The preexisting PAGE_NUMBER 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.
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 MASTER_CURRENT_PAGE and MASTER_TOTAL_PAGES and should only be used in text fields that have evaluationTime="Master" or evaluationTime="Auto" because they evaluate to null in all other contexts.
A typical text field using the two variables would look something like the following:

<element kind="textField" x="55" y="10" width="45" height="20">
  <expression><![CDATA[$V{PAGE_COUNT}]] ></expression>
</element>

Table of Contents

Special provisions are available for designing a report part that will show a Table of Contents of the generate document. Here is an example of how to create a table of contents with report's hyperlinks at the beginning of a document.