Dynamic Regions


RPE Region elements are helpful when you want to update/add information to a certain area in the output, not necessarily in the normal document flow. The RPE Infocenter further defines regions as:

Static elements that are used to display the text from another element in the template. When you generate the output, the content of that element displays where the region element is used in the template.

The key property of the regions is that they are static, meaning that you can only define them at design time. This is enforced by the fact that you can only use simple values for their name.

There are however many interesting scenarios where regions would need to be dynamic (created at runtime) and while you cannot achieve this using regions there is a way of doing  this for the Word and PDF outputs thanks to how regions are implemented in RPE.

For  Word and PDF the RPE regions are implemented using bookmarks. This was the natural choice as it allowed using regions defined in the style sheet and bookmarks, unlike regions, are dynamic elements so the result of combining these two deliberately in the template design will produce the desired dynamic regions.

The process of defining dynamic and using regions is quite simple and similar to the one of using static regions

  1. Define a unique name for the region. This is important as using the same name for multiple regions will result in undesired results.
    TIP use a variable for calculating and storing the region’s name as you’ll have to refer this name in at least 2 places. If instead you calculate this name in every location where it is needed you’ll have a harder time ensuring the consistency of the template.
  2. Add a bookmark to the template in the place where you want the region. This is the main difference between using regions and bookmarks.
  3. Use the name calculated at #1 for the bookmark’s name
  4. Set the “ensure unique” property of the bookmark to false
  5. Select the element you want sent to the region and use the name defined at 1 as the target region

NOTE Word regions are limited to 42 characters so when you define a unique region name you must ensure the name doesn’t exceed that limit.

NOTE this technique should not be used with multi-part Word outputs as the results are undefined

A sample template ( requires RPE 1.2 or higher) is available here.

The output for the example template using the XML sample data shipped with RPE is available here.

More information on regions is available here:

Advertisements

Author: Dragos Cojocari

Architect for Rational Publishing Engine

Leave a Reply

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

WordPress.com Logo

You are commenting using your WordPress.com 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 )

Google+ photo

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

Connecting to %s