13 Designing RTF Subtemplates
This chapter describes how to use RTF subtemplates to create and reuse functionality across multiple BI Publisher reports.
This chapter includes the following sections:
Understanding RTF Subtemplates
An RTF subtemplate is an RTF file that consists of one or more <?template:?> definitions, each containing a block of formatting or commands.
This RTF file, when uploaded to BI Publisher as a Sub Template object in the Catalog, can be called from other RTF templates.
The following graphic illustrates the composition of an RTF Sub Template.
Process Overview for Creating and Implementing RTF Sub Templates
You must follow this process to work with RTF sub templates.
Using a sub template consists of the following steps (described in the following sections):
Creating an RTF Subtemplate File
Enter the components or instructions in an RTF file. To define the instructions as a subtemplate, enclose the contents in these tags.
<?template:template_name?> ..subtemplate contents... <?end template?>
where
template_name is the name you choose for the subtemplate.
Note:
In a single RTF file, you can have multiple entries, to mark different subtemplates or segments to include in other files.
<?template:template_name?>
<?end template?>
For example, the following figure shows a sample RTF file that contains two subtemplates, one named commonHeader and one named commonFooter.
Calling a Subtemplate from a Main Template
There are two entries that you must make to call a subtemplate from a main template.
To implement the subtemplate in a main template, you must make two entries in the main template:
First, import the subtemplate file to the main template. The import syntax tells the BI Publisher engine where to find the Sub Template in the catalog.
Second, enter a call command to render the contents of the subtemplate at the position desired.
Importing the Subtemplate to the Main Template
Enter the import command anywhere in the main template prior to the call template command.
If you do not require a locale, enter the following:
<?import:xdoxsl:///path to subtemplate.xsb?>
where
path to subtemplate.xsb is the path to the subtemplate .xsb object in the catalog.
For example:
<?import:xdoxsl:///Executive/HR_Reports/mySubtemplate.xsb?>
Note:
If the subtemplate resides in a personal folder under My Folders, the command to import the subtemplate is:
<?import:xdoxsl:///~username/path to subtemplate.xsb?>
where username is your user name.
For example, if user myuser uploads a subtemplate called Template1 to a folder called Subtemplates under My Folders, the correct import statement is:
<?import:xdoxsl:///~myuser/Subtemplates/Template1.xsb?>
Calling the Subtemplate to Render Its Contents
You can also enter a call command to render the contents of the subtemplate at the position that you desire.
The following figure illustrates the entries required in a main template:
Importing a Localized Subtemplate
To designate the locale of the imported subtemplate, append the locale to the import statement as shown here.
<?import:xdoxsl:///{path to subtemplate.xsb}?loc={locale_name}?>
where
path to subtemplate.xsb is the path to the subtemplate .xsb object in the catalog
and
locale_name is the language-territory combination which comprises the locale. The locale designation is optional.
For example:
<?import:xdoxsl:///Executive/HR_Reports/mySubtemplate.xsb?loc=en-US?>
Note that you can also use ${_XDOLOCALE} to import a localized subtemplate based on the runtime user locale. For example:
<?import:xdoxsl:///Executive/HR_Reports/mySubtemplate.xsb?loc=${_XDOLOCALE}?>
Example
In this example, your company address is a fixed string that is displayed in all your templates. Rather than reproduce the string in all the templates, you can place it in one subtemplate and reference it from all the others.
At runtime the contents of the MyAddress subtemplate are fetched and rendered in the layout of the main template.
This functionality is not limited to just strings, you can insert any valid RTF template functionality in a subtemplate, and even pass parameters from one to the other. For examples, see When to Use RTF Subtemplates.
When to Use RTF Subtemplates
RTF subtemplates can be used in various scenarios.
Following are several common use-cases for RTF subtemplates.
Reusing a Common Layout
Frequently multiple reports require the same header and footer content.
By using an RTF subtemplate to contain this content, any global changes are simplified and require updating only the subtemplate instead of each individual layout.
Conditionally Displaying a Layout Based on a Value in the Data
Subtemplates can also be used to apply conditional layouts based on a value in the report data.
By using the RTF template "choose" command, you can instruct BI Publisher to apply a different <?template?> defined in the subtemplate file.
Note:
You cannot conditionalize the import statement for the subtemplate file. Instead, you import one subtemplate file and conditionalize the call statement. You define the multiple <?template?> options in the single subtemplate file.
Example
Assume you have a report that is sent to customers in India and the United States. You must apply a different address layout depending on the country code (COUNTRY_CODE) supplied in the data. This example uses the RTF templates if statement functionality to call the subtemplate with the appropriate address format.
The subtemplate file may look as follows:
<?template:US_Address?> <?US_Address_Field1?> <?US_Address_Field2?> <?US_Address_Field3?> <?end template?> <?template:IN_Address?> <?IN_Address_Field1?> <?IN_Address_Field2?> <?IN_Address_Field3?> <?end template?>
When the report is run, the address format is properly applied, depending on the value of COUNTRY_CODE in the data.
Conditionally Displaying a Layout Based on a Parameter Value
This example illustrates how to display a different layout based on a user parameter value or a selection from a list of values. The parameter can be passed to the RTF template and used to call a different <?template?> within the subtemplate file based on the value.
Note:
You cannot conditionalize the import statement for the subtemplate file.
Example
Assume in the report data model that you have defined a parameter named DeptName. Set up this parameter as type Menu and associate it to a list of values, enabling your user to make a selection from the list when he views the report in the Report Viewer (or when he schedules the report).
In the RTF main layout template, enter the following command to capture the value chosen by the user:
<?param@begin:DeptName?>
To display the layout based on this user selection, you can use an IF statement or a CHOOSE statement to evaluate the parameter value and call the associated subtemplate.
Use the CHOOSE statement when there are many conditional tests and a default action is expected for the rest of the values. For example, the Accounting, Sales, and Marketing departments each require a different layout. All other departments can use a default layout.
<?import:xdoxsl:///Executive/Department Expenses/DeptSubtemps.xsb?loc=en-US?>
<?param@begin:DeptName?>
<?choose:?>
<?when:$DeptName='Accounting'?>
<?call:tAccounting?>
<?end when?>
<?when:$DeptName='Sales'?>
<?call:tSales?>
<?end when?>
<?when:$DeptName='Marketing'?>
<?call:tMark?>
<?end when?>
<?otherwise:$>
<?call:tDefault?>
<?end otherwise?>
<?end choose:?>
When the user runs the report, the layout applied is determined based on the value of DeptName. For more information on CHOOSE statements in RTF templates, see Inserting Choose Statements.
Handling Simple Calculations or Repeating Formulae
Simple calculations can also be handled using an RTF subtemplate. More complex formulae should be handled with an XSL subtemplate.
Example
This example illustrates setting up a subtemplate to contain a formula to calculate interest.
The subtemplate performs the interest calculation on the data in this report and passes the result back to the main template. The sub template accommodates the possibility that multiple reports that call this functionality might have different tag names for the components of the formula.
Assume that you have the following XML data:
<LOAN_DATA> <LOAN_AMOUNT>6000000</LOAN_AMOUNT> <INTEREST_RATE>.053</INTEREST_RATE> <NO_OF_YEARS>30</NO_OF_YEARS> </LOAN_DATA>
Adding Translations to an RTF Subtemplate
RTF subtemplates offer the same support for translations as RTF template files.
You can upload multiple translated RTF files under a single Subtemplate definition and assign the appropriate locale. These are displayed in the Templates region, as shown in the following figure.
Or you can generate an XLIFF (.xlf) file of the translatable strings, translate the strings, and upload the translated file. These are displayed in the Translations region, as shown in the following figure:
At runtime, the appropriate subtemplate localization is applied based on the user's account Preference setting for Report Locale for reports viewed online; or, for scheduled reports, based on the user's selection for Report Locale for the scheduled report.
The XLIFF files for subtemplates can be generated individually, then translated, and uploaded individually. Or, if you perform a catalog translation that includes the Sub Template folders, the strings from the subtemplate files are extracted and included in the larger catalog translation file. When the catalog translation file is uploaded toBI Publisher, the appropriate translations from the catalog file are displayed in the Translations region of the Sub Template definition.
For more information on translations, see Translation Support Overview and Concepts.