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.

On Wednesday 3PM London time (or 10AM Orlando time) we will give a Community Web-Ex about how Reporting Changes in the upcoming Citrus-Release.

Aside from officially announcing the switch from our well-loved, most-hated-by-sales “0.8.x” version numbering schema, we will shed some light what new features we have and on how the new features will make your reporting life easier. During the first part, we will give an short overview about the new stuff (and the reasons behind it) and also explain the changed relationship of the new reporting engine and the BI-Platform. As we all know, that there is no other truth than working code, the second part will demonstrate how to utilize parameters, the new datasources and the Rich-Text engine (along with the magic wizard), to build a simple interactive ad-hoc reporting solution. Building this solution should be fast, so we’ll have plenty of time for questions and answers at the end of the Web-Ex.

The web-ex information will be available via the Pentaho-Forum.

As regular reader you may have noticed that the appearance of this blog has changed. After running into a couple of issues and being faced with the option to either manually fix every single link in the old Blog-system or to switch over to a PHP driven system, I was torn. I dont trust PHP enough to let it loose on my system for security reasons. I admit, I love Java beyond reason. What other system allows you to lock down the VM so safely that evil-doers cannot do evil at all?

Luckily, over the past year, I stumbled accross the perfect solution: Quercus. Quercus is a PHP interpreter written in Java. It runs great. Heck, it is not optimized at all (in the sense of compiling PHP to Bytecode, as, for instance, the Rhino JavaScript library does), yet still it outperforms the native PHP interpreters (thanks to Tomcat).

Does it work? Yes, as proven by this machine. Is it complicated to set up? Not at all. Just drop the WAR file in, add your JDBC-driver, copy your PHP files in, run.

And now that writing Blog-Entries is no longer a pain, I’m tempted to write more often.

Post scriptum:

I just noticed that the friggin’ import lost all links, all tables and all images thanks to a overly active “html validator” that strips all tags it does not understand. So maybe I exchanged one can of worms with a just another one.

Update: It seems the “kses.php” file (or Quercus’ interpretation of the same) is to blame for the troubles. The file contains a check on whether a attribute validation definition is a empty-string. For some reason, Quercus  believes that a empty array *is* a empty string. Forcing it to use a stricter check (three equals signs instead of two) solved the issue so far.