Master your page-breaks in the Pentaho Report Designer

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.

This entry was posted in Uncategorized on by .

About Thomas

After working as all-hands guy and lead developer on Pentaho Reporting for over an decade, I have learned a thing or two about report generation, layouting and general BI practices. I have witnessed the remarkable growth of Pentaho Reporting from a small niche product to a enterprise class Business Intelligence product. This blog documents my own perspective on Pentaho Reporting's development process and our our steps towards upcoming releases.

6 thoughts on “Master your page-breaks in the Pentaho Report Designer

  1. Smoodo

    Thanks for taking the time to write this article. This topic is still cryptic. Screenshots and/or examples would really help convey the idea.

  2. Sergio Ramazzina

    Yes it is really good but I agree with smoodo about the idea of having screenshots/examples. Moreover I’ve got a question for you. What about having the possibility to control the break of the page? I mean, I’ve a report with 3 banded subreports. Sometimes the 3rd subreport is longer than expected and the pagebreak functionality takes part of this 3rd subreport content in the new page. My requirement is to be able to take all of the content of the 3r subreport in the new page as soon as that subreport is longer than the length of the page. Is that possible by manually setting some attributes in the page-break section to let the reporting engine work this way?



  3. Thomas Morgner

    I think I will extend the article a bit – and yes, screenshots will probably help illustrating the structures I am talking about.

    Sergio, if you use any of the subreports, then you can solve it by simply setting the subreport’s style “keep-together” to true. Subreports for a box around their content and that box inherits the subreport’s keep-together style property.

  4. shutterblogs

    Was directed here from Pentaho forums. While the article is helpful I still could not figure out how to do it with limited screenshots and/or illustrations. Please, it would really be beneficial to the community.

  5. TSUDA Hitoshi

    I’m really really appreciated to your article… I can go on my job!
    Btw, Report Designer is so complicated that I feel like screaming in my office…

  6. Jai

    Even When Layout is set to BLOCK the pagebreak occurs but value is not obtained in the second page. Did anyone face this issue???
    Please guide me if anyone can…

Comments are closed.