Report Structure in Jaspersoft Studio

A report is defined by means of a type page. This is divided into different horizontal portions named bands. When the report is joined with the data generating the print, this section are printed many times according to their function (and according to the rules that the report designer has set). For instance, the page header is repeated at the beginning of every page, while the detail band is repeated for each record.

The Report Lifecycle

The report lifecycle starts with report design. Designing a report means creating a template, such as a form containing blank space, that can be filled with data. Some portions of a page defined in this way are reused, others stretch to fit the content, etc..

This template is saved as an XML file sub-type called JRXML (“JR” for JasperReports). This file contains information about the report layout, including complex formulas to perform calculations, an optional query to retrieve data out of a data source, and other functionality.

The life cycle can be divided into two distinct action sets:

Tasks executed during the development phase: design and planning of the report, and compilation of a Jasper file source, the JRXML.
Tasks that must be executed in run time: loading of the Jasper file, filling of the report, and export of the print in a final format.

The main role of Jaspersoft Studio in the cycle is to design a report and create an associated jasper file, though it is able to preview the result and export it in all the supported formats. Jaspersoft Studio provides support for a wide range of data sources and allows users to create custom data sources, thereby becoming a complete environment for report development and testing.

When you design a report using Jaspersoft Studio, you are creating a JRXML file, which is an XML document that contains the definition of the report layout. The layout is completely visual, so you can ignore the underlying structure of the JRXML file. Before executing a report, the JRXML must be compiled in a binary object called a Jasper file. Jasper files are what you need to ship with your application in order to run the reports.

Report execution is performed by passing a Jasper file and a data source to JasperReports. There are many data source types. You can fill a Jasper file from an SQL query, an XML file, a .csv file, an HQL (Hibernate Query Language) query, a collection of JavaBeans, and others. If you don't have a suitable data source, JasperReports allows you to write your own custom data source. With a Jasper file and a data source, JasperReports is able to generate the final document in the format you want.

Jaspersoft Studio also lets you configure data sources and use them to test your reports. In many cases, data-driven wizards can help you design your reports much quicker. Jaspersoft Studio includes the JasperReports engine itself to let you preview your report output, test, and refine your reports.

Understanding Bands

The type page is divided into nine predefined bands to which new groups are added. In addition, Jaspersoft Studio manages a heading band (group header) and a recapitulation band (group footer) for every group.

A band is as wide as the page width (right and left margins excluded). However, its height, even if it is established during the design phase, can vary during print creation according to the contained elements; it can “lengthen” toward the bottom of a page in an arbitrary way. This typically occurs when bands contain subreports or text fields that have to adapt to the content vertically. Generally, the height specified by the user should be considered “the minimal height” of the band. Not all bands can be stretched dynamically according to content; in particular the column footer, page footer, and last page footer bands are statically sized.

The sum of all band heights (except for the background) has to always be less than or equal to the page height minus the top and bottom margins.

Band Types

The following table contains brief descriptions of the available bands:

Band Name



The title band is the first visible band. It is created only once and can be printed on a separate page. It is not possible during design to exceed the report page height (top and bottom margins are included). If the title is printed on a separate page, this band height is not included in the calculation of the total sum of all band heights.

Page Header

The page header band allows you to define a page header. The height specified during the design phase usually does not change during the creation process, except for the insertion of vertically resizable components such as a text fields. The page header appears on all printed pages in the position defined during the design phase. Title and summary bands do not include the page header when printed on a separate page.

Column Header

The column header band is printed at the beginning of each detail column. Usually labels containing the column names of a tabular report are inserted in this band.

Group Header

A report can contains zero or more group bands which permit the collection of detail records in real groups. A group header is always accompanied by a group footer (both can be independently visible or not). Different properties are associated with a group. They determine its behavior from the graphic point of view. It is possible to always force a group header on a new page or in a new column and to print this band on all pages if the bands below it overflow the single page (as a page header, but at group level). It is possible to fix a minimum height required to print a group header: if it exceeds this height, the group header band is printed on a new page (please note that a value too large for this property can create an infinite loop during printing).

Group Footer

The group footer band completes a group. Usually it contains fields to view subtotals or separation graphic elements, such as lines.

Column Footer

The column footer band appears on at the end of every column. Its dimension are not resizable at run time (not even if it contains resizable elements such as subreports or text fields with a variable number of text lines).

Page Footer

The page footer band appears on every page where there is a page header. Like the column footer, it is not resizable at run time.

Last Page Footer

If you want to make the last page footer different from the other footers, it is possible to use the special last page footer band. If the band height is 0, it is completely ignored, and the layout established for the common page is used for the last page.


The summary band allows you to insert fields containing total calculations, means, or any other information you want to include at the end of the report.


The background enables you to create watermarks and similar effects, such as a frame around the whole page. It can have a maximum height equal to the page height.

Specifying Report Properties

To edit report properties, click on the Edit page format button in the properties view of the report, or right click on the report itself, and select Page Format from the contextual menu, to see the page properties.

In the dialog that appears you can change the page dimensions.

The unit of measurement used by Jaspersoft Studio and JasperReports is the pixel. However, it is possible to specify report dimension using other units of measurement, such as centimeters, millimeters, or inches. Note that because the dimensions management is based on pixels, some rough adjustments can take place when viewing the same data using different units of measurement.In the following table there is a list of standard measures and their dimensions in pixels.

Page Type

Dimensions in Pixels





























































By modifying width and height, it is possible to create a report of whatever size you like. Although Jaspersoft enables you to create pixel-perfect reports, the page orientation options, Landscape or Portrait, are there because they are used by certain report exporters. The page margin dimensions are set by means of the four options on the Page Margin tab.


Pages, one or more of which make up a report, presents bands are independent from the data (such as the title or the page footers) and other bands that are printed only if there are one or more data records to print (such as the group headers and the detail band). These last sections can be divided into vertical columns in order to take advantage of the available space on the page. A column does not concern the record fields, but it does concern the detail band. This means that if you have record with ten fields and you desire a table view, ten columns are not needed. However, the element must be placed correctly to have a table effect. Ten columns are returned when long records lists (that are horizontally very narrow) are printed.

Next, let's set up columns in a report as an example. Create a new report from File > New > Jasper Report. Choose as template BlankA4 and name it ColumnExample. Use Sample DB - Database JBDC Connection for the data adapter, with the following SQL query: select * from orders. Fields from the database are discovered. Double-click SHIPNAME, to add it to the report field and click Next twice. Finally, click Finish.From

the outline view drag the SHIPNAME field in the report in the detail band, resize the detail band, and remove the unused bands. Go to the Preview tab to see the report compiled.

By default the number of columns is 1, and its width is equal to the entire page, except the margins. The space between columns is zero by default. Most of the page is unused. If multiple columns are used, this report would look better. On the Page Format dialog set the number of columns to two and compile the report to see the changes.

Jaspersoft Studio automatically calculates maximum column width according to the margins and the page width. If you want to increase the space between the columns, increase the value of the Space field.

The restricted area is used to mark every column after the first, to show that all the elements should be placed in the first column; the other columns' is replicated automatically during compilation. If you want you can also put elements in the other columns, but in most cases you need only the first. It is not recommended that you use parts of the report as margins and columns after the first, if they have to be considered as though they were a continuation of the first.

Multiple columns are commonly used for print-outs of very long lists (for example, a phone directory). It is important to remember that when you have more than one column, the width of the detail band and of linked bands is reduced to the width of the columns.

The sum of the margins, column widths, and space between columns has to be less or equal to the page width. If this condition is not met, the compilation results in an error.

Advanced Options

From the properties tab of the report there are many other options for the report configuration. Select the report root note from the outline view, and in the Properties tab you see:

Report Name: It is a logical name, independent form the source file's name, and is used only by the JasperReports library (for example, to name the produced java file when a report is compiled).
Title on a new page: This option specifies that the title band is to be printed on a new page, which forces a page break at the end of the title band. In the first page only the title band is printed. However this page is still included in total page count.
Summary on a new page: This option is similar to Title on a new page except that the summary band is printed as the last page. If you need to print this band on a new page, the new page only contains the summary band.
Summary with page header and footer: This option specifies if the summary band is to be accompanied by the page header and the page footer.
Floating column footer: This option forces the printing of the column footer band immediately after the last detail band (or group footer) rather than the end of the column. This option is used, for example, when you want to create tables using the report elements.
When no data type: When an empty data is supplied as the print number (or the SQL associated with the report returns no records), an empty file is created (or a a stream of zero bytes is returned). This default behavior can be modified by specifying what to do in the case of absence of data. The possible values for this field are:
     NoPages: This is the default value; the final result is an empty buffer.
     BlankPage: This returns an empty page.
     AlSectionNoDetails: This returns a page containing all bands except for the detail band.