It is funny how at times the same question or problem flares up from many disconnected developers leading them to ask the same question in just a few days. The most recent incident of this sort of questions could be paraphrased as:

How the $%&§ do these pagebreaks work

Pentaho Reporting allows you to control Pagebreaks via two style settings: “pagebreak-before” and “pagebreak-after” indicating whether you want to start a new page before or after the band or section prints. Pagebreaks are usually set on any of the root level bands. Root level bands are all main sections you see in the report, like the “group-header”, “group-footer”, “report-header” or “report-footer” or the “details” section. Pagebreaks on these bands are always honoured, but you can add breaks to other locations as well.
Whether pagebreaks are allowed on a certain element depends on both the element type and the position of that element in the report layout.

Pagebreak rulez

Pagebreaks are allowed on all root level bands except the page header and -footer. The pagebreak request will be ignored for repeated instances of the group- or details-header and footer that are printed in the header and footer area of a page. A pagebreak inside a page-header or footer would not make any sense and could send the poor Pentaho reporting engine into a infinite loop of destruction when each new page triggers the generation of a new page.

Pagebreaks can be defined on all subreports. The pagebreak will only be honoured for inline-subreports, but will be ignored for banded-subreports. You can define the pagebreak on the banded-subreport’s report-header to achieve the same effect.

Pagebreaks can be placed on normal bands within the same root-level band. The pagebreak will only be honoured if the layout for this band follows some simple rules. All parents of the band must have a block-layout – more on that later.

Defined Pagebreaks will be ignored on a master-report or on groups, even though we will support breaks on the group-object in later versions. For now, if you want to start a new page for a group, put your pagebreak on the group’s group-header instead.

So in short:

• Pagebreaks can be added to all root bands
• Inline subreports can have pagebreaks
• Normal bands can have pagebreaks if they are in a block-layout.
• MasterReport, Group and Banded-Subreports cannot have pagebreaks.

Get pagebreaks on bands and inline-subreports to work

Pagebreaks work on all bands as long as the band sits in a valid pure block-level context.

A block layout is a layout strategy where each element inside the layout context spans the full width of the parent section. Elements are stacked below each other like paragraphs in a text book. To learn more about the layout strategies, I recommend you to read about “Element Layout Strategies in Pentaho Reporting“.

In Pentaho Reporting 3.5 and newer the report layouter places all root level bands into a block layout. Therefore for the outer-most master report, all root bands span the full width of the page and new bands are added directly below the previously printed bands.

A element’s layout context is a pure block-level context when all the parent bands of the element have a block-layout. In that case, the element or band itself is guaranteed to span the whole width of the page. This gives us a natural cut-off point for starting new pages.

So what does that mean for your layouts?

If you want to add a pagebreak to your bands or inline-subreports, the parent band (the band that contains your band or subreport) must have the style property layout set to block. And then this band’s parent must have a block-layout until you come to the root-level band itself, which must be set to layout: block as well.

Create multi-page details bands

You can use the block-layout technique to divide any root level band into multiple bands that have page-breaks between the sub-sections. And here is how you do it:

1. Select your root-level band, for instance the details band.
2. Switch to the style-tab on the right-hand side table, and locate the “layout” style.
3. Set the layout to “block”
4. Add two or more bands to the root band by dragging them into the root band editor.
5. Add pagebreaks as needed to these sub-bands.

With those simple rules in mind, pagebreaks should no longer be the mysterious feature anymore.