Best practices for table design in RPE

With RPE there is usually more than one way to achieve a goal and tables make no exception. However not all methods are equal and some designs are better/faster/more maintainable than others.

This article documents the guidelines the RPE team recommends for designing RPE tables, with a focus on the Word and PDF outputs.

1. Iterate on rows not on tables

Consecutive tables in Word are merged in a single table which  encourages a template design where a table is generated per element in the data source. This design works, especially with older RPE versions, as a side effect of how tables are handled in RPE/Word but it has significant disadvantages including but not limited to performance penalties.


In the above design the header row has the “once per table” property set on true. The result is a single table but as you can see from the next image it’s not a nice looking table.

NOTE older RPE releases produced a better Word output for this specific scenario and this changed with the upgrade of the component that RPE uses to produce Word output. The upgrade was necessary as it RPE to work faster, fix many output problems and also gave RPE the ability to update fields etc.

You can fix the table’s layout by specifying cell widths however that comes at the cost of an increased cost in template maintenance. In addition this design is suboptimal in performance and makes for a less readable template design. The right way to address this is by moving the iteration from the table level on the row level.


With this design RPE will produce the table faster and with a correct layout with no other settings.


Even better you should iterate on a container inside the table so that you can add calculations or conditionally exclude tables as needed or produce multiple rows per query element which can render different properties based on runtime conditions.


2. Allow Word/RPE to resize the table

In most cases allowing Word and RPE to resize the table will result in a very nice looking table so if you do not need to follow a specific table layout with precise column width it’s better to leave this task on RPE/Word. The recommended settings in most vase are the following:

  • table auto fit – autofit to window
  • resize to fit contents – true
  • fixed cell width in column – true
  • cell widths – not set


3. Allow Word to break text in cells

Word’s resizing tables algorithm depends heavily on the data as well and the possibility to break the text in the cells. The best results are obtained if Word can break the texts in columns and by default this is only done on word boundaries. If you have very large words as some languages do then Word will not be able to break the columns resulting in a suboptimal layout or even the table overlapping the page’s boundaries.

In the scenarios where the tables overflow the page boundaries you cannot user the recommendations made in the previous point. Instead you need to enable Word to break the columns’ text as needed and for this you need to set the “resize to fit contents” property to false in the RPE template, see below.


The “resize to fit contents” maps to the “Automatically resize to fit contents” property in Word. Doing a “Autofit to window” in Word will make the table look better again but you will notice that it also sets this flag back to true.


NOTE with “Resize to fit contents” set to false the “Autofit to Window” algorithm will produce tables with equal columns making it less useful.  The best results in this scenario are achieved if you leave “table auto fit” empty and explicitly set column widths. You do not need to set the widths for all columns, it is usually enough to set the widths for the columns you know will have wider content.

4. Use styles for the cells in heading rows

As with any other RPE template element, using styles allows for an easy and consistent layout for your tables even across multiple templates.


Author: Dragos Cojocari

Architect for Rational Publishing Engine

5 thoughts on “Best practices for table design in RPE”

  1. Iterating on the row seems to work best when there is only one table in the document for that module. If you need to break up the table into separate tables by document section, and intersperse those tables with non-tablular Object Heading and Object text, it is not as straight-forward as stated.

    1. That is correct Bonnie. Depending on how the data is structured and how you want your document organized you might need to iterate on tables. But whenever possible the row iteration is to be preferred to the table iteration.

  2. I’ve got a long landscape table where, because there is quite a lot of text in some of the cells, it overruns the page at the bottom (width-wise is fine) on some pages. Is there any way to force this overrunning text onto the next page?

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s