Jasper Reports - Subreport usage demonstration

This post is part of Jasper Reports demo documentation project, please read that post for information on downloading the discussed demo files

jasperreports-3.7.0/demo/samples/subreport

This demonstration will teach you how to reuse sub-reports for enhancing report visual layout. Subreports among other things allow you to achieve high level of data presentation complexity with relatively small overhead.

a Subreport in Jasper terminology is single jrxml report file which is designed to be included in a master report, the master report should pass parameters to the subreport (For ex. rowId or street address) which are accessed by the subreport using $P{"parameterName"} notation. Optional feature for subreport is return parameters which allow passing information from calculations done within the subreport back to the master report, under the hood these are variables which are defined in the master report and passed to the subreport element (we will see an example of this later in the post).


Lets start with the basics setup required to get the report demo running:

First you will need to start the hsqldb database.

Next open all 3 reports in iReports.

• MasterReport.jrxml
• ProductReport.jrxml
• AddressReport.jrxml

Test the report is working:

1. In iReports, assuming you followed the hsqlsdb setup guide you should select "jdbc:hsqldb:hsql://localhost" as your datasource.
2. Make sure you have focus on the MasterReport tab
3. Now click "Preview"
1. In the popup windows select "Use Default"

This should bring a semi-working report that looks something like this:

To configure a fully functional we will need to do some adjustment steps, as we are operating the report from iReport instead from Java code.

MasterReport has has a parameter called ProductsSubreport of type net.sf.jasperreports.engine.JasperReport this parameter can be used in production environment to dynamically supply the subreport Class Instance that will be used by one of this subreport elements (more on this later). For now, lets change this to supply a fixed sub report element so that we can preview the full report in iReports as Jasper team designed it.

Locate in iReports the element's:

1. MasterReport -> Details 1 -> $P{ProductsSubreport} then set the following fields:
   
   
   
   
   • Subreport Expression = "ProductReport.jasper"
   • Expression Class = java.lang.String
   
   
   
   
   
2. MasterReport -> Parameters -> ProductsSubreport then set the following fields:
   
   
   
   • Use as a prompt = [ ] (unselected)
   
   
   
   
   

Now if you try to preview the report again the following will be shown:

Good! The report is fully operation. Lets start analyzing.

Understanding Report logical Structure

This report prints product orders grouped by city. The report layout is as following:

== Report Title =
 Heading + Total number of orders
== Page Title ==
Page Heading
== Details ==
= First page =
City name     COUNTER: Number of address ordered in this city
= Next n pages =
City name     cont


Then 2 lists order side by side displaying:
First list =  Products ordered by people in current city
Second list = Address that made orders in current city

== Page Footer ==
Page X out of XXX

Understanding Report JRXML structure

MasterReport.jrxml

Master Report :: Query
The main report is based on the following SQL query: SELECT City FROM Address GROUP BY City ORDER BY City which should self explentionary.


Master Report -> Title
This section contains static text and a graphical horizontal bar.

Pay attention to the Text Field that as part of his expression uses the dynamically calculated variable $V{ProductTotalPrice} this variable is returned from the sub reports called during report filling phase and the results are summarized by the engine. More on this later.

Master Report -> Page Header 
Nothing special here. Static text that will be printed at the start of each page.

Master Report -> Details 1

The heart of the report.

It is important to understand that a details band can grow beyond single page size, Jasper has special treatment for these situation via settings which can be set on each element as we shall see next:

On the first page we want to print "CityName"  COUNTER Addresses, on the following pages for the same city OTOH all we want to print is "CityName"  cont

The idea is that if a city band grows to several pages we will reprint the "CityName" and the text "Cont"

TextField $F{City} has the setting Print Repeated Values and Print When Details Overflows which causes it repeat on each page, even when the band for current city grows beyond 1 page size.


TextField $V{CityAddressCount} + " addresses" has the setting Print Repeated Values which will allow this field to be printed even if 2 cities have the same number of addresses but note this Print When Details Overflows is turned off which causes this text to be printed only on the first page of the band !

Label (continued) has the setting Print Repeated Values turned off and Print When Details Overflows enabled. This cause this label to be printed only on overflowed bands (meaning only on 2nd pages and following...).

Subreport $P{ProductsSubreport} is the embedding of the ProductReport subreport. Note this report gets the Database connection from the MasterReport, we also pass a parameter to this report City = $F{City}. This report returns a variable, the way this is implement in Jasper Reports is as following: We define a variable in the master report ProductTotalPrice, then we pass this variable to the subreport which sets values into this variable. Then, after the subreport evaluation has ended in the MasterReport we can use this variables value. In the present context we use this method to calculate a summary (TOTAL) of the price of all the products being evaluated by the subreport. Note that as part of the definition of the variable on the subreport element we configure Calculation Type = Sum this allows the engine to do the summary of this variable (which is passed to many subreport's - A subreport is evaluated for each city). See Variables section for another note on the ProductTotalPrice variable.


Master Report -> Variables


ProductTotalPrice this variable is used by the MasterReport to display the sum of the price of all products that have been evaluated by the subreport ProductReport note this variable has the property Calculation = System meaning that it is being manipulated separately (not by the engine). This is actually a little hack (IMHO) because we do sum it using the engine only we do it on the Subreport $P{ProductsSubreport} variable configuration properties. Just in case you wondered: Yes! it works.

ProductReport.jrxml

To be continued...

AddressReport.jrxml

To be continued...