Implementations of this interface represent various bands in the report template.
JasperReports works with templates that are structured into multiple sections, like any
traditional reporting tool. A report can contain the following
sections: background, title, summary, page header, page footer, last page footer,
column header and column footer.
At report-filling time, the engine iterates through the virtual
records of the supplied report data source and renders each report section when
appropriate, depending on each section's defined behavior.
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.
Sections are made of one or more bands. Bands are portions of the report template that
have a specified height and width and can contain report elements like lines, rectangles,
images, and text fields. These bands are filled repeatedly at report-generating time and
make up the final document.
When declaring the content and layout of a report section, in an JRXML report design,
use the generic element
Report sections, sometimes referred to as report bands, represent a feature and
functionality common to almost all reporting tools.
attribute in a report band declaration specifies the height in pixels for that
particular band and is very important in the overall report design.
The elements contained by a certain report band should always fit the band's dimensions;
this will prevent potentially bad results when generating the reports. The engine issues a
warning if it finds elements outside the band borders when compiling report designs.
Preventing Band Split
In some cases it is desirable to keep the whole contents of a given band in one piece to
prevent page breaks when the band stretches beyond its initial specified height. To do
this, use the
attribute, as follows:
- The band never splits within its declared height. The band
will not start rendering on the current page if the remaining available space is not at
least equal to the band's declared height. However, if the band stretches on the
current page, the region that is added to the original height is allowed to split onto
the next page.
- The band starts to render normally, but if the bottom
of the page is reached without finishing the band, the whole contents of the band
that are already being laid out are moved to the next page. If the band does not fit
on the next page, the split occurs normally, as band split prevention is effective
only on the first split attempt
- The band is allowed to split anywhere except above its topmost element
If a split type is not specified, the default is given by the
All the report sections allow users to define a report expression that will be evaluated at
runtime to decide if that section should be generated or skipped when producing the
This expression is introduced by the
tag, which is available
element of the JRXML report design and should always return a
object or null.