Report Sections



We discussed the structure of a simple report template in the chapter Getting Started. On similar lines, JasperReports structures the report template into multiple sections. Sections are portions of the report that have a specified height and can contain report objects like lines, rectangles, images, or text fields.

The report engine iterates through the virtual records of the supplied report data source, at report filling time. Depending on each section's defined behavior, the engine then renders each report section when appropriate. For instance, the detail section is rendered for each record in the data source. When page breaks occur, the page header and page footer sections are rendered as needed.

In JasperReports, terminology and report sections are also called as report bands. Sections are made up of one or more bands. These sections are filled repeatedly at report-generating time and prepare the final document.

Main Sections

A report template in JasperReports has the following main sections −

<title></title>

<pageheader></pageheader>

<columnheader></columnheader>

<groupheader></groupheader>

<detail></detail>

<groupfooter></groupfooter>

<columnfooter></columnfooter>

<pagefooter></pagefooter>

<lastpagefooter></lastpagefooter>

<summary></summary>

<nodata></nodata>

<background></background>

The following table summarizes each of the sections −

S.NO Section and Description
1

Title

This section appears only once at the beginning of the report.

2

Page Header

This section appears at the beginning of each page in the generated document.

3

Column Header

This section appears at the beginning of each column in the generated document. If the report has only one column defined, then column header and footer sections are ignored.

4

Group Header

This section is introduced by a report group (chapter Groups). Each time the grouping expression changes its value, the group header section is printed above the detail section. In case, if more than one group is defined, the group header is printed in the order of group definition.

5

Detail

This section is repeated for each line of data supplied by the report's data source. The detail section can be made of multiple bands.

6

Group Footer

This section is introduced by a report group (chapter Groups). The group footer section is printed below the detail section before the value of the grouping expression changes. The group footer is always printed for the last line of data in data source. In case, if more than one group is defined, the group footer is printed in the reverse order of group definition.

7

Column Footer

This section appears at the bottom of each column. If the report's column count is 1, then column header and footer sections are ignored.

8

Page Footer

This section appears at the bottom of each page.

9

Last Page Footer

This section replaces the regular page footer on the last page of the report. In case, the summary section is also present, then this might not be the very last page of the document. This section is sometimes useful when summary information has to be displayed at the bottom of the last page.

10

Summary

This section appears only once at the end of the report.

11

No Data

This section is printed when the When No Data Print report property is set to No Data Section. If the <noData> section is defined in the report template, and if the data source is empty, then the <noData> section will be the only one taken into account at fill time, and its content will produce the report output.

12

Background

The background section is displayed on every page and cannot overflow to the next page. Elements placed on this section are evaluated at page initialization time and are displayed in the background. All other page objects are displayed on top of the background objects. This section is useful for creating page watermarks.

Section, Elements and Attribute Relation

The following diagram shows the elements and attributes relationship in a section of a report.

Report Sections

Section Elements

All the above mentioned report sections are optional. But any report template will have at least one such section. Each of these sections contains a single <band> element as its only sub-element. A <band> can contain zero or more following sub-elements −

<line>, <rectangle>, <ellipse>, <image>, <staticText>, <textField>, <subReport>, or <elementGroup>

Each of these elements must contain a single <reportElement> as its first element (except elementGroup). A <reportElement> determines how data is laid out for that particular element. Unlike variables and parameters, report elements are not required to have a name, because normally you do not need to obtain any individual element inside a report template.

The table below summarizes the attributes of <reportElement> −

Attribute Description Valid Values
x Specifies the x coordinate of the band element. An integer value indicating the x coordinate of the element in pixels. This attribute is required.
y Specifies the y coordinate of the band element. An integer value indicating the y coordinate of the element in pixels. This attribute is required.
width Specifies the width of the band element. An integer value indicating the element width in pixels. This attribute is required.
height Specifies the height of the band element. An integer value indicating the element height in pixels. This attribute is required.
key Unique identifier of band element. A unique string value.
stretchType Specifies how does the element stretch when the containing band stretches

NoStretch (default) − The element will not stretch.

RelativeToTallestObject − The element will stretch to accommodate the tallest object in its group.

RelativeToBand − The element will stretch to fit the band's height.

positionType Specifies the element's position when the band stretches.

Float − The element will move depending on the size of the surrounding elements.

FixRelativeToTop (default) − The element will maintain a fixed position relative to the band's top.

FixRelativeToBottom − The element will maintain a fixed position relative to the band's bottom.

isPrintRepeatedValues Specifies if repeated values are printed.

true (default) − Repeated values will be printed.

false − Repeated values will not be printed.

mode Specifies the background mode of the element Opaque, Transparent
isRemoveLineWhenBlank Specifies if the element should be removed when it is blank and there are no other elements in the same horizontal space. true, false
isPrintInFirstWholeBand Specifies if the element must be printed in a whole band, that is, a band that is not divided between report pages or columns. true, false
isPrintWhenDetailOverFlows Specifies if the element will be printed when the band overflows to a new page or column. true, false
printWhenGroupChanges Specifies that the element will be printed when the specified group changes. A string value.
forecolor Specifies the foreground color of the element. Either a hexadecimal RGB value preceded by the # character, or one of the following predefined values: black, blue, cyan, darkGray, gray, green, lightGray, magenta, orange, pink, red, yellow, white.
backcolor Specifies the background color of the element. Same as Valid Values for forecolor

Section Attributes

Following are the attributes of a report section −

Height

Height of the section specifies the height in pixels for that particular section and is very important in the overall report design.

Print When Expression

A Boolean expression that determines whether the section should be printed or not.

Split Allowed

A flag indicating whether the section is allowed to split when it does not fit on the current page. If true, the section will be transferred to the next page. Note that in case, the section does not fit on the next page, then the section will be split regardless of the flag's value. splitType can take following values −

  • splitType="Stretch:" Splits stretched content. If the section stretches on the current page (if the available space is less than declared height), the region that is added to the original height is allowed to split onto the next page.

  • splitType="Prevent:" Prevent split on first attempt. If the section does not fit on the next page, the split occurs normally, as band split prevention is effective only on the first split attempt.

  • splitType="Immediate:" Split immediately. The band is allowed to split anywhere except above, its topmost element.

Example

To demonstrate each section, let's write report template (jasper_report_template.jrxml). Save this file to C:\tools\jasperreports-5.0.1\test directory. In this file, we would be displaying a text in each of the sections (we discussed above). The contents of the file are as given below −

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

<jasperReport xmlns = "http://jasperreports.sourceforge.net/jasperreports"
   xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation = "http://jasperreports.sourceforge.net/jasperreports
   http://jasperreports.sourceforge.net/xsd/jasperreport.xsd"
   name = "jasper_report_template" pageWidth = "300" pageHeight = "300" 
   columnWidth = "300" leftMargin = "0" rightMargin = "0" 
   topMargin = "0" bottomMargin = "0" >

   <title>
      <band height = "50">
         
         <textField>
            <reportElement x = "100" y = "16" width = "100" height = "20"/>
            <textElement/>
            
            <textFieldExpression>
               <![CDATA["Title"]]>
            </textFieldExpression>
        
         </textField>
      
      </band>
   </title>
   
   <pageHeader>
      <band height = "40">
         
         <textField>
            <reportElement  mode = "Opaque" x = "100" y = "10" 
               width = "90" height = "20"/>
            
            <textElement>
               <font isBold = "true"/>
            </textElement>
            
            <textFieldExpression>
               <![CDATA["Page Header"]]>
            </textFieldExpression>
         </textField>
      
      </band>
   </pageHeader>
   
   <columnHeader>
      <band height = "40">
            
         <textField>
            <reportElement  x = "100" y = "10" width = "90" height = "20"/>
            
            <textElement>
               <font isItalic = "true"/>
            </textElement>
            
            <textFieldExpression>
               <![CDATA["Column Header"]]>
            </textFieldExpression>
         </textField>
      
      </band>
   </columnHeader>
   
   <detail>
      <band height ="40">
         
         <textField>
            <reportElement mode = "Opaque" x = "100" y = "10" 
               width = "90" height = "20" backcolor = "#99CCFF"/>
            <textElement/>
            
            <textFieldExpression>
               <![CDATA["Report Details"]]>
            </textFieldExpression>
         </textField>
      
      </band>
   </detail>
   
   <columnFooter>
      <band height = "40">
         
         <textField>
            <reportElement  x = "100" y = "10" width = "90" height = "20"/>
            <textElement/>
            
            <textFieldExpression>
               <![CDATA["Column Footer"]]>
            </textFieldExpression>
         </textField>
      
      </band>
   </columnFooter>
   
   <pageFooter>
      <band height = "40">
         
         <textField>
            <reportElement  x = "100" y = "10" width = "90" height = "20"/>
            <textElement/>
            
            <textFieldExpression>
               <![CDATA["Page Footer"]]>
            </textFieldExpression>
         </textField>
      
      </band>
   </pageFooter>
   
   <lastPageFooter>
      <band height = "40">
         
         <textField>
            <reportElement  x = "100" y = "10" width = "90" height = "20"/>
            <textElement/>
            
            <textFieldExpression>
               <![CDATA["Last Page Footer"]]>
            </textFieldExpression>
         </textField>
      
      </band>
   </lastPageFooter>
   
   <summary>
      <band height = "40">
         
         <textField>
            <reportElement  x = "100" y = "10" width = "90" height = "20"/>
            <textElement/>
            
            <textFieldExpression>
               <![CDATA["Summary"]]>
            </textFieldExpression>
         </textField>
      
      </band>
   </summary>
	
</jasperReport>

The java code to fill and generate the report is given below. Let's save this file JasperReportFill.java to C:\tools\jasperreports-5.0.1\test\src\com\tutorialspoint directory.

package com.tutorialspoint;

import net.sf.jasperreports.engine.JREmptyDataSource;
import net.sf.jasperreports.engine.JRException;
import net.sf.jasperreports.engine.JasperFillManager;

public class JasperReportFill {
   public static void main(String[] args) {
      String sourceFileName = "C://tools/jasperreports-5.0.1/test/" + 
         "jasper_report_template.jasper";

      try {
         JasperFillManager.fillReportToFile(sourceFileName, null,
            new JREmptyDataSource());
      } catch (JRException e) {
         // TODO Auto-generated catch block
         e.printStackTrace();
      }

   }
}

Here, we use an instance of JREmptyDataSource when filling reports to simulate a data source with one record in it, but with all the fields in this single record being null.

Report Generation

We will compile and execute the above file using our regular ANT build process. The contents of the file build.xml (saved under directory C:\tools\jasperreports-5.0.1\test) are as below.

The import file - baseBuild.xml is picked up from the chapter Environment Setup and should be placed in the same directory as the build.xml.

<?xml version = "1.0" encoding = "UTF-8"?>
<project name = "JasperReportTest" default = "viewFillReport" basedir = ".">
   
   <import file = "baseBuild.xml" />
   <target name = "viewFillReport" depends = "compile,compilereportdesing,run"
      description = "Launches the report viewer to preview 
      the report stored in the .JRprint file.">
      
      <java classname = "net.sf.jasperreports.view.JasperViewer" fork = "true">
         <arg value = "-F${file.name}.JRprint" />
         <classpath refid = "classpath" />
      </java>
		
   </target>
   
   <target name = "compilereportdesing" description = "Compiles the JXML file and
      produces the .jasper file.">
      
      <taskdef name = "jrc"
         classname = "net.sf.jasperreports.ant.JRAntCompileTask">
         <classpath refid = "classpath" />
      </taskdef>
      
      <jrc destdir = ".">
         <src>
            <fileset dir = ".">
               <include name = "*.jrxml" />
            </fileset>
         </src>
         <classpath refid = "classpath" />
      </jrc>
   
   </target>
	
</project>

Next, let's open command line window and go to the directory where build.xml is placed. Finally, execute the command ant -Dmain-class=com.tutorialspoint.JasperReportFill (viewFullReport is the default target) as follows −

C:\tools\jasperreports-5.0.1\test>ant -Dmain-class=com.tutorialspoint.JasperReportFill
Buildfile: C:\tools\jasperreports-5.0.1\test\build.xml

clean-sample:
   [delete] Deleting directory C:\tools\jasperreports-5.0.1\test\classes
   [delete] Deleting: C:\tools\jasperreports-5.0.1\test\jasper_report_template.jasper
   [delete] Deleting: C:\tools\jasperreports-5.0.1\test\jasper_report_template.jrprint

compile:
   [mkdir] Created dir: C:\tools\jasperreports-5.0.1\test\classes
   [javac] C:\tools\jasperreports-5.0.1\test\baseBuild.xml:28:
   warning: 'includeantruntime' was not set, defau
   [javac] Compiling 1 source file to C:\tools\jasperreports-5.0.1\test\classes

compilereportdesing:
   [jrc] Compiling 1 report design files.
   [jrc] log4j:WARN No appenders could be found for logger
   (net.sf.jasperreports.engine.xml.JRXmlDigesterFac
   [jrc] log4j:WARN Please initialize the log4j system properly.
   [jrc] log4j:WARN See http://logging.apache.org/log4j/1.2/faq.html#noconfig for more info.
   [jrc] File : C:\tools\jasperreports-5.0.1\test\jasper_report_template.jrxml ... OK.

run:
   [echo] Runnin class : com.tutorialspoint.JasperReportFill
   [java] log4j:WARN No appenders could be found for logger
   (net.sf.jasperreports.extensions.ExtensionsEnviro
   [java] log4j:WARN Please initialize the log4j system properly.

viewFillReport:
   [java] log4j:WARN No appenders could be found for logger
   (net.sf.jasperreports.extensions.ExtensionsEnviro
   [java] log4j:WARN Please initialize the log4j system properly.

BUILD SUCCESSFUL
Total time: 18 minutes 22 seconds

As a result of above compilation, a JasperViewer window opens up as in the screen below −

Jasper Report Section Example

Here, we can see in each of the sections a text is printed. It is to be noted that as JRXML contains a <lastPageFooter> element, it will be displayed in the last page of the report instead of the <pageFooter> element being displayed. The <columnHeader> and <columnFooter> elements will only be displayed on the report, if it has more than one column.

Advertisements