General information

All table based output targets (HTML, Execl, Layouted CSV) have some layout restrictions. These layout restrictions also apply to the PlainText output target:

• The elements must be aligned properly, they must not overlap. When overlapping, the left element gets preferred over the right element, and top elements have a higher preferrence level as bottom elements.

• The elements must be large enough to contain the element. This is important when specifying the cell/line height, the elements height must be greater than the minimum height.
  
  For Excel/Html cells the minimum height is equal to the font height, so you'll just have to make sure that the cell is able to print at least one line of text.
  
  For PlainText, the line height is defined by the LPI setting, if LPI (lines per inch) is set to 10, then the minimum height of a line should be 72/10 points, so specifying a element height of 8 is safe. If LPI is set to 6, then the line height should be at least 72/6, so a element height of 12 should be ok.

• The Epson- and IBM plain text output does not handle 16-bit character sets. When using the PlainText output target to send the output to an printer, make sure that your printer is able to handle the used text encoding.

• When specifying colors for the Excel target, then these colors are translated into one of the predefined excel color constants. This translation tries to find the nearest color, if that fails, the colors could look weird. Using one of the predefined AWT colors is always safe, everything else should work, but there are no guarantees.

The table-export algorithm

In Pentaho Reporting Classic, all Report-Elements are positioned somewhere on a canvas. Whenever an band is being printed, the layouting system jumps in an computes the final layout for the band and all child elements. After the layouting is complete, each element has some valid 'bounds', which describe where the painter would have to place the element on the canvas.

The table-generator's work starts after all elements have a valid layout. For each visible element in the band, the layouter takes the bounds and generates a column or row break for each edge position. All bands of the report are added to a single table. Therefore the table's column will be based on all generated column breaks of all bands.

Pentaho Reporting Classic has two table-export modes. In the 'simple' export mode, the table-generator ignores the right and bottom edge of the child elements (but not for the root-level band). If a 'complex' layout is requested, all boundary informations are taken into account.

Theory is dry, lets take a look at some numbers:

Lets assume we have a root-level band with a width of 500 point and a height of 200 points. The band has two childs, a label and a text-field. I'll specify the bounds as absolute positions, (X1,Y1) denotes the upper-left corner, and (X2,Y2) denotes the lower right corner.

The bounds of all elements involved are:

• Band: X1=0, Y1=0, X2=500, Y2=200
• Label: X1=100, Y1=0, X2=300, Y2=100
• Textfield: X1=100, Y1=100, X2=250, Y2=200
  

Let's follow the table-generator's steps. We assume that the complex layouting is used.

1. The Band gets added: As there are no column breaks yet, A column break will be added for X1=0 and X2=500. A rowbreak is added at Y1=0 and Y2=200.
   The first break always marks the start of the table, and the last break marks the end (and total-width) of the table. The table now consists of a single cell, that has a width of 500 points and a height of 200 points.

1. The Label gets added: As there is no column break for X1=100, a new column break is inserted. The table's only cell splits into two columns.

A column break for X2 gets inserted at position 300. The table now contains 3 columns.

The Label's Y1 does not cause a row-break, as the band already caused one at this position. A row break for Y2 gets inserted at position 100. The table now consists of two rows.

1. The text field is added to the table. X1 does not cause a column break, as there is already one at this position. X2 causes a new column break at position 250. Note that the label already occupies the cell from X=100 to X=300. This cell will now span two columns. There is already a column break for the text-field's Y1 position (at Y=100, caused by the labels bottom edge) and for the Y2 position (at Y=200, caused by the band's bottom edge).

If the table-generator uses the simple algorithm, the resulting table gets simplified in a second step. The column breaks at position 250 and 300 have been caused by a right edge of an report element. These breaks now get removed, so that the resulting table looks like this:

Now it should be clear, that the table-generator works best, if all elements are properly aligned. All elements that should go into one row or column have to start at the same X and y positions. If the strict layouting mode is used, they also must end at the same position. Elements that should go into neighbouring cells must share a common edge. And finally: Elements that do not start at position Zero will cause an empty column or row.

In the next post, I'll cover how Pentaho Reporting Classic computes cell backgrounds and borders.