Chapter 13: Using tables
13.1. Block tables
If you are familiar with HTML, you will understand the basic tags for use with tables in RML.
Just as in HTML, you use a tag to tell rml2pdf that a table is on the way (in this case
<blockTable>; rather than <table>), and another one
to end it. Within the <blockTable> and </blockTable> tags, <tr>
and </tr> enclose the rows (from Table Row); and within each table row,
<td> and </td> enclose each individual cell (from Table
Data).
So, the simplest <blockTable> in RML will look something like this:
<blockTable>
<tr>
<td>This</td><td>is</td>
</tr>
<tr>
<td>a</td><td>blockTable.</td>
</tr>
</blockTable>
This produces a table that looks like this:
| This | is |
| a | blockTable. |
Figure 24: A very simple blockTable
In this short example, we are just using plain old vanilla text in the
table cells. But we can do more. <blocktable>
allows you to use paragraphs and the <para>
tag. This means that you can use bold,
italics, colors, fonts, greek...
anything you can use in a paragraph. And you can use multiple paragraphs
inside a table cell.
| |
|
| |
|
Figure 25: A slightly more complex blockTable
The main thing that makes this slightly more complex than a very simple table is the fact
that you must give rowHeights and colWidths to the <blockTable> to use paras.
This makes sense - paragraphs fit into the available space on a page. In a table, they
must fit into the available space in that cell. If you haven't defined how high and wide
that cell will be, then there is no way for rml2pdf to know how to make it flow in that
cell. (If you get an error message saying "Flowables cell can't have auto width", then
this is the thing to check - you have probably omitted the rowHeights or colWidths).
When you are using paragraphs inside a table, you must not put any text outside the
<para>...</para> tags. The only exception to this rule is whitespace - you can put
spaces and tabs outside the <para> tag, but nothing else.
One other thing to be aware of is that if you use a para inside a table, it will
ignore the text attributes you have used for that table and instead use the attributes
for paragraphs. This can be a plus, (since it allows you to use already defined
paragraph styles) but can take you by surprise if
weren't expecting it.
As an example, here is the RML that generated the above table:
<blockTable rowHeights="1.25cm,1.25cm" colWidths="4cm,4cm" >
<tr>
<td> <para>This is a <b>more</b> complex <font color="red">blockTable</font>.</para> </td>
<td> <para>This is a more <i>complex</i> blockTable.</para> </td>
</tr>
<tr>
<td> <para><font face="Helvetica">This is a more complex blockTable.</font></para> </td>
<td> <para>This is <greek>a</greek> more <font color="blue"><i>complex</i></font> blockTa<greek>b</greek>le.</para> </td>
</tr>
</blockTable>
13.2. Block table attributes
This is useful, but there's a lot more to <blocktable>s
than that! The actual <blocktable> tag can have a number of optional attributes:
style : blockTables can have a style set in the
stylesheet in the same way as
paragraphs can. If you have set a style for your blockTable,
you can refer to it by name with this attribute and apply it to your table. (More details on
how to do it appear in the section on the
<blockTableStyle> tag below).
colWidths : If you use this attribute, it takes a comma-separated list of the
width of each column in your blockTable. This allows you to vary the widths to match the width
of the content of each column. If you do use it, you should be careful to make sure that there
is one width given for every column in your table.
rowHeights : As colWidths is to columns, rowHeights is to rows. It also takes a
comma-separated list, in this case for the heights of the rows in your table.
repeatRows : If you have a large table that splits over multiple pages, you may
well want certain information appearing on all of them. Column headers are one example of this
sort of information. The repeatRows attribute allows you to do this. repeatRows takes a
single number as an argument or a ',' separated list of numbers. In the case of a single number
the rows up to and including this row are repeated as "headers" on each section of the table
that appears on a new page. If a list of rows is given then this is a zero based list of rows
to repeat. So if the list (1,) is given then the first table header will have rows 0 & 1
and any succeeding split table will have the original second row as header. This allows for
the first appearance of a table to have additional rows which may be unwanted later.
13.3. Block table styles
blockTables are a flowable, so the actual <blockTable>
tag will appear in the story section of your RML document. You
can use the <blockTableStyle> tag to set the appearance
of your blockTable. This appears in the stylesheet section
of your document, and can be used for more than one table. You
can set up how all the blockTables in your document will look in one blockTableStyle tag if
you want.
The <blockTableStyle> tag is a container for a number of other tags, and needs to be paired
with a terminal <blockTableStyle> tag. This works in the same way as
<styleSheet></styleSheet>, <pageGraphics></pageGraphics>,
and other tags of that sort.
For all of the attributes in blockTableStyle, they refer to a square or rectangular "block"
inside the table. This can be as many or as few cells as you want - not necessarily a single
cell. This "block" aspect to the attributes is reflected in their names, and gave the table
style its name for consistency. (It was felt that since most of these attributes started with
"block...", the table tag should itself be called blockTable to keep things simple).
The way the block is described may seem unusual to you if you are not used to programming. The x and y co-ordinates are still given as X,Y (or if you like "Row,Column", rather than the spreadsheet "A1" model), but the numbering starts from 0 rather than 1. This makes the top left-hand cell (0,0). As well as this, the numbers may also be negative. If this is the case, then rml2pdf will count backwards from the end of the last cell. So (-1,-1) is the bottom right hand cell in a table, (-2,-2) is the one up and to the left of that, and so on.
The tags that blockTableStyle can contain are:
blockfont sets the font to be used in a block of your table.
It has one mandatory attribute: name.
It has four optional attributes: size, leading, start and stop.
blockTextColor
This sets the color that will be used for the text in a block of your table.
It has one required attribute: colorName.
It has two optional attributes: start and stop.
blockLeading
This sets the leading that will be used for the text in a block of your table.
It has one required attribute: length.
It has two optional attributes: start and stop.
blockAlignment
This sets the alignment of the text in a block of your table.
It has one required attribute: value. (This can be LEFT, RIGHT, CENTER, or CENTRE).
It has two optional attributes: start and stop.
blockValign
This sets how the contents of a block of cells in your table are aligned in the vertical direction.
It has one required attribute: value. (This can be TOP, MIDDLE, or BOTTOM, and defaults to BOTTOM).
It has two optional attributes: start and stop.
blockLeftPadding
This sets the padding (i.e. blank space) between the contents of a cell and left-hand edge of the cell
(for a block of cells in your table).
It has one required attribute: length.
It has two optional attributes: start and stop.
blockRightPadding
This sets the padding between the contents of a cell and right-hand edge of the cell
(for a block of cells in your table).
It has one required attribute: length.
It has two optional attributes: start and stop.
blockBottomPadding
This sets the padding between the contents of a cell and bottom edge of the cell (for a block of cells).
It has one required attribute: length.
It has two optional attributes: start and stop.
blockTopPadding
This sets the padding between the contents of a cell and top edge of the cell (for a block of cells).
It has one required attribute: length.
It has two optional attributes: start and stop.
blockBackground
This sets the color to be used for the background for a block of cells in your table.
It has one required attribute: colorName.
It has two optional attributes: start and stop.
lineStyle
This allows you to use lines to border your table.
It has two required attributes: kind (with the options of GRID, BOX, OUTLINE, INNERGRID, LINEBELOW, LINEABOVE, LINEBEFORE and LINEAFTER), and colorName (which must be the name of a color).
It has three optional attributes: thickness, start and stop.
blockSpan
This allows you to merge a range of cells provided start and end grid coordinates. e.g.
<blockSpan start="0,0" stop="1,0"/> to merge the first two cells of the first row.
roundedCorners
This allows you to specify rounded corners for your table.
It has one optional attribute: radii which takes a string value "none" or a comma
separated list of numbers eg "5,5,0,0" representing the top left, top right, bottom
left and bottom right corner radii.
A radius of 0 is square and missing trailing
values are assumed 0.
The radius actually used will be the minimum of the corner
cell width/height and the requested radius. Border lines passing through the exact corners
are curved an octant at each corner.
13.4. More about block tables
A couple of cautions about blockTables
A few final things to be aware about when using tables: in RML,
table cells (as contained by the <td> and </td> tags) can
only contain one of two different sets of data. Either a table cell can contain string
forms (text and the
<getName> and <pageNumber>
tags) or it can contain a sequence of flowables (tags such as
<pre>, <para> and the various
heading tags). It is not possible to mix both of these forms in the same cell (though
you can mix them in the same table).
Putting strings into table cells is quicker than using paragraphs. Paragraphs need to work out when to 'wrap' text, strings don't. So you should avoid using paragraphs inside tables unless you really need to (or you don't mind things slowing down).
When you are doing a big database report, wherever possible use separate smaller tables to contain parts of your data rather than one huge table. If you don't use many 'mini-tables' to contain small groups of rows but instead decide to do a big 1,000-row table, you will notice a significant loss of speed in the generation of your output PDF.
This also makes it much easier to design complex grouped reports; for each group header, footer or detail block you can design one table style and keep them all independent of each other.
13.5. Using block table styles
Now that we have seen what the blockTable's attributes are, and seen a
summary of <blockTableStyle>,
here are some examples that show you how they can be used together.
The following section shows a number of examples of blockTables. Each one shows a page
with the RML listing, followed by a separate page with the result of that table. Each
listing contains comments to point out what each tag involved with the blockTable is doing.
Example 16 - Colors and fonts in tables
This example show various ways of setting the text color
(blockTextColor),
font (blockfont)
and background color (blockBackground)
for regions in a blockTable.
Notice the various ways of specifying a region within the table. Also notice the way we
have defined heights for the rows and widths for the columns in the blocktable tag.
EXAMPLE 16
Figure 26: Output from EXAMPLE 16
<?xml version="1.0" encoding="iso-8859-1" standalone="no" ?>
<!DOCTYPE document SYSTEM "../rml.dtd">
<document filename="example_10.pdf">
<template>
<pageTemplate id="main">
<pageGraphics>
</pageGraphics>
<frame id="first" x1="72" y1="72" width="451" height="698"/>
</pageTemplate>
</template>
<stylesheet>
<blockTableStyle id="myBlockTableStyle">
<!-- This sets a font for every cell from the start of the
second row down to the bottom right hand corner -->
<blockFont name="Courier-Bold" start="0,1" stop="-1,-1"/>
<!-- This sets a font for the first row -->
<blockFont name="Helvetica-BoldOblique" size="24" start="0,0" stop="3,0"/>
<!-- This sets a textColor for all the text in the table -->
<blockTextColor colorName="black"/>
<!-- This sets a textColor for the first row -->
<!-- (Since it comes after the above setting, -->
<!-- it overides it for this row) -->
<blockTextColor colorName="white" start="0,0" stop="3,0"/>
<!-- This sets a textColor a column - also overiding -->
<!-- the first textColor setting for this row -->
<blockTextColor colorName="blue" start="1,1" stop="1,6"/>
<!-- This sets a background color for the first row -->
<blockBackground colorName="red" start="0,0" stop="3,0"/>
<!-- This sets a background color for the rest of the table -->
<blockBackground colorName="cornsilk" start="0,1" stop="-1,-1"/>
<!-- This sets a background color for an individual cell -->
<!-- This has to go AFTER the above blockBackground, -->
<!-- otherwise it would be overpainted by the cornsilk color -->
<blockBackground colorName="lightcoral" start="3,3" stop="3,3"/>
</blockTableStyle>
</stylesheet>
<story>
<title>Example 16 - colors and fonts in tables</title>
<spacer length = "1cm"/>
<blockTable style="myBlockTableStyle"
rowHeights="3.5cm,2cm,2cm,2cm,2cm,2cm,2cm"
colWidths="4cm,4cm,4cm,4cm"
>
<tr><td>Cell 0,0</td><td>Cell 1,0</td><td>Cell 2,0</td><td>Cell 3,0</td></tr>
<tr><td>Cell 0,1</td><td>Cell 1,1</td><td>Cell 2,1</td><td>Cell 3,1</td></tr>
<tr><td>Cell 0,2</td><td>Cell 1,2</td><td>Cell 2,2</td><td>Cell 3,2</td></tr>
<tr><td>Cell 0,3</td><td>Cell 1,3</td><td>Cell 2,3</td><td>Cell 3,3</td></tr>
<tr><td>Cell 0,4</td><td>Cell 1,4</td><td>Cell 2,4</td><td>Cell 3,4</td></tr>
<tr><td>Cell 0,5</td><td>Cell 1,5</td><td>Cell 2,5</td><td>Cell 3,5</td></tr>
<tr><td>Cell 0,6</td><td>Cell 1,6</td><td>Cell 2,6</td><td>Cell 3,6</td></tr>
</blockTable>
</story>
</document>
Colors and fonts in table cells
As an alternative to specifying cell properties using block table styles, RML also allows
some cell styles to be specified as attributes of the td tag.
Figure 26: Output from EXAMPLE 16
<blockTable colWidths="5cm,5cm" style="myBlockTableStyle1">
<tr><td>fontName</td><td fontName="Courier">Courier</td></tr>
<tr><td>fontName</td><td fontName="Helvetica">Helvetica</td></tr>
<tr><td>fontSize</td><td fontSize="8">8</td></tr>
<tr><td>fontSize</td><td fontSize="14">14</td></tr>
<tr><td>fontColor</td><td fontColor="red">red</td></tr>
<tr><td>fontColor</td><td fontColor="blue">blue</td></tr>
<tr><td>leading</td><td leading="16">leading
is
16</td></tr>
<tr><td>leading</td><td leading="12">leading
is
12</td></tr>
<tr><td>leftPadding</td><td leftPadding="10">10</td></tr>
<tr><td>leftPadding</td><td leftPadding="16">16</td></tr>
<tr><td>rightPadding</td><td rightPadding="10" align="right">10</td></tr>
<tr><td>rightPadding</td><td rightPadding="24" align="right">24</td></tr>
<tr><td>topPadding</td><td topPadding="10">10</td></tr>
<tr><td>topPadding</td><td topPadding="24">24</td></tr>
<tr><td>bottomPadding</td><td bottomPadding="10">10</td></tr>
<tr><td>bottomPadding</td><td bottomPadding="24">24</td></tr>
<tr><td>background</td><td background="pink">pink</td></tr>
<tr><td>background</td><td background="lightblue">lightblue</td></tr>
<tr><td>align</td><td align="left">left</td></tr>
<tr><td>align</td><td align="center">center</td></tr>
<tr><td>align</td><td align="right">right</td></tr>
<tr><td>-
vAlign
-</td><td vAlign="top">top</td></tr>
<tr><td>-
vAlign
-</td><td vAlign="middle">middle</td></tr>
<tr><td>-
vAlign
-</td><td vAlign="bottom">bottom</td></tr>
</blockTable>
Example 17 - lines and alignment in tables
This example shows the various vertical and horizontal alignments you can give text in a table, as well as a few ways to use lines.
EXAMPLE 17
Figure 27: Output table from EXAMPLE 17
<template>
<pageTemplate id="main">
<pageGraphics>
</pageGraphics>
<frame id="first" x1="72" y1="72" width="451" height="698"/>
</pageTemplate>
</template>
<stylesheet>
<blockTableStyle id="myBlockTableStyle">
<!-- Set fonts -->
<blockFont name="Courier-Bold" size="10" start="0,1" stop="-1,-1"/>
<blockFont name="Helvetica-BoldOblique" size="10" start="0,0" stop="3,0"/>
<!-- This sets a textColor for all the text in the table -->
<blockTextColor colorName="black"/>
<!-- Another example of blockTextColor -->
<blockTextColor colorName="green" start="2,2" stop="3,3"/>
<!-- This sets a blockAlignment for the whole table -->
<blockAlignment value="CENTER"/>
<!-- These overrides the above -->
<blockAlignment value="RIGHT" start="3,0" stop="3,-1"/>
<blockAlignment value="LEFT" start="0,1" stop="0,-1"/>
<!-- This sets the vertical alignment for one row -->
<blockValign value="TOP" start="0,0" stop="-1,0"/>
<!-- This sets the vertical alignment for one cell -->
<blockValign value="MIDDLE" start="2,2" stop="2,2"/>
<!-- Use of linestyles -->
<lineStyle kind="GRID" colorName="silver"/>
<lineStyle kind="LINEBELOW" colorName="orangered" start="0,0"
stop="-1,0" thickness="5"/>
<lineStyle kind="LINEAFTER" colorName="maroon" start="1,1"
stop="1,6" thickness="1"/>
</blockTableStyle>
</stylesheet>
<story>
<title>Example 11 - lines and alignment in tables</title>
<spacer length="1cm"/>
<blockTable style="myBlockTableStyle2"
rowHeights="2cm,2cm,2cm,2cm,2cm,2cm,2cm"
colWidths="4cm,3cm,3cm,4cm"
>
<tr>
<td>(a=LEFT)(VA=TOP)</td>
<td>(VA=TOP)</td>
<td>(VA="TOP")</td>
<td>(a=RIGHT)(VA=TOP)</td>
</tr>
<tr>
<td>(a=LEFT)</td>
<td>1,1</td>
<td>Cell 2,1</td>
<td>(a=RIGHT)</td>
</tr>
<tr>
<td>(a=LEFT)</td>
<td>1,2</td>
<td>(VA=MIDDLE)</td>
<td>(VA=MDL)(a=RIGHT)</td>
</tr>
<tr>
<td>(a=LEFT)</td>
<td>1,3</td>
<td>(VA=MIDDLE)</td>
<td>(VA=MDL)(a=RIGHT)</td>
</tr>
<tr>
<td>(a=LEFT)</td>
<td>1,4</td>
<td>2,4</td>
<td>(a=RIGHT)</td>
</tr>
<tr>
<td>(a=LEFT)</td>
<td>1,5</td>
<td>2,5</td>
<td>(a=RIGHT)</td>
</tr>
<tr>
<td>(a=LEFT)</td>
<td>1,6</td>
<td>2,6</td>
<td>(a=RIGHT)</td>
</tr>
</blockTable>
<spacer length="15"/>
<para>a=value for <i>blockAlignment</i></para>
<para>VA=value for <i>blockValign</i></para>
<para><i>MDLE=MIDDLE for VA in cells 3,2 and 3,3</i></para>
</story>
Example 18 - images and padding in tables
This example shows images in a table and the way to use the various padding attributes.
For comparison purposes:
The cells that contain pictures in this table are all 166 pixels in height and 161 pixels in width.
Where padding is used, it has a value of 20 pixels horizontally or 40 pixels vertically.
EXAMPLE 18
Figure 28: Output from EXAMPLE 18
<?xml version="1.0" encoding="iso-8859-1" standalone="no" ?>
<!DOCTYPE document SYSTEM "rml.dtd">
<document filename="example_18.pdf">
<template>
<pageTemplate id="main">
<pageGraphics>
</pageGraphics>
<frame id="first" x1="72" y1="72" width="451" height="698"/>
</pageTemplate>
</template>
<stylesheet>
<blockTableStyle id="myBlockTableStyle">
<blockBackground colorName="silver" start="0,0" stop="-1,0"/>
<blockBackground colorName="darkslategray" start="0,1" stop="-1,1"/>
<blockBackground colorName="silver" start="0,2" stop="-1,2"/>
<blockBackground colorName="darkslategray" start="0,3" stop="-1,3"/>
<blockBackground colorName="silver" start="0,4" stop="-1,4"/>
<blockBackground colorName="darkslategray" start="0,5" stop="-1,5"/>
<blockAlignment value="CENTER"/>
<blockValign value="MIDDLE"/>
<!-- Set fonts -->
<blockFont name="Helvetica-BoldOblique" size="10"/>
<!-- set the left and right padding for cells in first and -->
<!-- third columns remember, cell numbering starts from ZERO, not ONE -->
<blockLeftPadding length="20" start="0,0" stop="0,-1"/>
<blockRightPadding length="20" start="2,0" stop="2,-1"/>
<!-- set the top and bottom padding for cells in first and third rows -->
<blockBottomPadding length="40" start="0,0" stop="-1,0"/>
<blockTopPadding length="40" start="0,2" stop="-1,2"/>
<!-- set the top and bottom padding for the last row -->
<blockBottomPadding length="40" start="-1,4" stop="-1,4"/>
<blockTopPadding length="40" start="0,4" stop="0,4"/>
<!-- Use of linestyles -->
<lineStyle kind="GRID" colorName="darkblue"/>
</blockTableStyle>
<paraStyle name="paddingTableStyle"
fontName="Helvetica-BoldOblique"
fontSize="10"
textColor="white"
alignment="CENTER"
/>
</stylesheet>
<story>
<title>Example 18 - images and padding in tables</title>
<spacer length="1cm"/>
<blockTable style="myBlockTableStyle"
rowHeights="166,28,166,28,166,28"
colWidths="161,161,161"
>
<tr>
<td>
<illustration width="141" height="90">
<image file="images/replogo.gif"
x="0" y="0"
width="141" height="90"/>
<stroke color="deepskyblue"/>
<lineMode width="3"/>
<lines>
0 0 141 0
141 0 141 90
141 90 0 90
0 90 0 0
</lines>
</illustration>
</td>
<td>
<illustration width="141" height="90">
<image file="images/replogo.gif"
x="0" y="0"
width="141" height="90"/>
<stroke color="deepskyblue"/>
<lineMode width="3"/>
<lines>
0 0 141 0
141 0 141 90
141 90 0 90
0 90 0 0
</lines>
</illustration>
</td>
<td>
<illustration width="141" height="90">
<image file="images/replogo.gif"
x="0" y="0"
width="141" height="90"/>
<stroke color="deepskyblue"/>
<lineMode width="3"/>
<lines>
0 0 141 0
141 0 141 90
141 90 0 90
0 90 0 0
</lines>
</illustration>
</td>
</tr>
<tr>
<td>
<para style="paddingTableStyle">
<b>blockLeftPadding</b> with <b>blockBottomPadding</b>
</para>
</td>
<td>
<para style="paddingTableStyle">
just blockBottomPadding
</para>
</td>
<td>
<para style="paddingTableStyle">
<b>blockRightPadding</b> with <b>blockBottomPadding</b>
</para>
</td>
</tr>
<tr>
<td>
<illustration width="141" height="90">
<image file="images/replogo.gif"
x="0" y="0"
width="141" height="90"/>
<stroke color="deepskyblue"/>
<lineMode width="3"/>
<lines>
0 0 141 0
141 0 141 90
141 90 0 90
0 90 0 0
</lines>
</illustration>
</td>
<td>
<illustration width="141" height="90">
<image file="images/replogo.gif"
x="0" y="0"
width="141" height="90"/>
<stroke color="deepskyblue"/>
<lineMode width="3"/>
<lines>
0 0 141 0
141 0 141 90
141 90 0 90
0 90 0 0
</lines>
</illustration>
</td>
<td>
<illustration width="141" height="90">
<image file="images/replogo.gif"
x="0" y="0"
width="141" height="90"/>
<stroke color="deepskyblue"/>
<lineMode width="3"/>
<lines>
0 0 141 0
141 0 141 90
141 90 0 90
0 90 0 0
</lines>
</illustration>
</td>
</tr>
<tr>
<td>
<para style="paddingTableStyle">
<b>blockLeftPadding</b> with <b>blockTopPadding</b>
</para>
</td>
<td>
<para style="paddingTableStyle">
just blockTopPadding
</para>
</td>
<td>
<para style="paddingTableStyle">
<b>blockRightPadding</b> with <b>blockTopPadding</b>
</para>
</td>
</tr>
<tr>
<td>
<illustration width="141" height="90">
<image file="images/replogo.gif"
x="0" y="0"
width="141" height="90"/>
<stroke color="deepskyblue"/>
<lineMode width="3"/>
<lines>
0 0 141 0
141 0 141 90
141 90 0 90
0 90 0 0
</lines>
</illustration>
</td>
<td>
<illustration width="141" height="90">
<image file="images/replogo.gif"
x="0" y="0"
width="141" height="90"/>
<stroke color="deepskyblue"/>
<lineMode width="3"/>
<lines>
0 0 141 0
141 0 141 90
141 90 0 90
0 90 0 0
</lines>
</illustration>
</td>
<td>
<illustration width="141" height="90">
<image file="images/replogo.gif"
x="0" y="0"
width="141" height="90"/>
<stroke color="deepskyblue"/>
<lineMode width="3"/>
<lines>
0 0 141 0
141 0 141 90
141 90 0 90
0 90 0 0
</lines>
</illustration>
</td>
</tr>
<tr>
<td>
<para style="paddingTableStyle">
blockLeftPadding with blockTopPadding
</para>
</td>
<td>
<para style="paddingTableStyle">
no padding
</para>
</td>
<td>
<para style="paddingTableStyle">
blockRightPadding with blockBottomPadding
</para>
</td>
</tr>
</blockTable>
</story>
</document>