Designing RTF Subtemplates

This chapter covers the following topics:

Understanding RTF Subtemplates
Process Overview for Creating and Implementing RTF Subtemplates
Creating an RTF Subtemplate File
Calling a Subtemplate from Your Main Template
When to Use RTF Subtemplates
Adding Translations to an RTF Subtemplate

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 figure illustrates the composition of an RTF Sub Template:

the picture is described in the document text

Process Overview for Creating and Implementing RTF Subtemplates

Using a subtemplate consists of the following steps (described in the following sections):

Create the RTF file containing the common components or processing instructions that you wish to include in other templates.
Create the calling or "main" layout and include the following two commands:
- import - to import the subtemplate file to the main layout template.
- call-template - to execute or render the subtemplate contents in the main layout.
Test your template and subtemplate.

Tip: You can use the BI Publisher Desktop Template Viewer to test your main layout plus subtemplate before loading them to the catalog. To do so, you must alter the import template syntax to point to the location of the subtemplate in you local environment. See Testing Subtemplates from the Desktop.
Upload the main template to the report definition and create the Sub Template object in the catalog. See Creating the Sub Template Object in the Catalog.

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 the following tags:

<?template:template_name?>
      ..subtemplate contents...
<?end template?>

where

template_name is the name you choose for the subtemplate.

Note that in a single RTF file, you can have multiple

<?template:template_name?> 
<?end template?>

entries, to mark different "subtemplates" or segments to include in other files.

For example, the following sample RTF file contains two subtemplates, one named commonHeader and one named commonFooter:

the picture is described in the document text

Calling a Subtemplate from Your Main Template

To implement the subtemplate in your main template, you must make two entries in your 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?>
```

Calling the Subtemplate to Render Its Contents

In the position in the main template where you want the subtemplate to render, enter the call-template command, as follows:
```
<?call-template:template_name?>
```
where

template_name is the name you assigned to the contents in the template declaration statement within the subtemplate file (that is, the <?template:template_name?> statement).

The following figure illustrates the entries required in your main template:

the picture is described in the document text

Importing a Localized Subtemplate

To designate the locale of the imported subtemplate, append the locale to the import statement as follows:

<?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 appears in all your templates. Rather than reproduce the string in all your templates, you can place it in one subtemplate and reference it from all the others.

In an RTF file enter the following template declaration:

<?template:MyAddress?>
My Company
500 Main Street
Any City, CA 98765
<?end template?>

Create a Sub Template in the catalog in the following location: Customer Reports/Templates.
Upload this file to the Sub Template and save it as "Common Components" (BI Publisher will assign the object the .xsb extension).
In your main template, enter the following import statement in a form field or directly in the template:
```
<?import:xdoxsl:///Customer Reports/Templates/Common Components.xsb?>
```
In your main template, in the location you want the address to appear, enter
```
<?call-template:MyAddress?>
```

At runtime the contents of the MyAddress subtemplate will be 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 the next section: When to Use RTF Subtemplates.

When to Use RTF Subtemplates

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 will be 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 your subtemplate file.

IMPORTANT: 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 will be sent to customers in India and the United States. You need to 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.

Your subtemplate file may look like the following:

<?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?>

Create a Sub Template in the catalog in the following location:

Customers/Invoice Reports

Upload the RTF file and save the Sub Template as "Addresses".
In your main template enter the following to import the Sub Template:
```
<?import:xdoxsl:///Customers/Invoice Reports/Addresses.xsb?>
```

In the location where you want the address to display, enter the following:

     <?if:COUNTRY_CODE=’USA’?>
        <?call:US_Address?>    
     <?end if?>   
     <?if:COUNTRY_CODE=’IN’?>         
        <?call:IN_Address?>          
     <?end if?>

When the report is run, the address format will be 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.

IMPORTANT: You cannot conditionalize the import statement for the subtemplate file.

Example

Assume in your report data model you have defined a parameter named DeptName. You set up this parameter as type Menu and associated 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 your 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.

Create an RTF file and include the following template declarations:

<?template:tAccounting?>
   -  -  -  Specific Accounting Layout here  -  -  - 
<?end template?>

<?template:tSales?>
   -  -  -  Specific Sales Layout here  -  - -
<?end template?> 

<?template:tMark?>
   -  -  -  Specific Marketing Layout here - -
<?end template?> 

<?template:tDefault?>
   -  -  -  Default Layout here  -  - -
<?end template?>

Create a Sub Template in the catalog in the following location:

Shared Folders/Executive/Department Expenses

Upload the RTF file and save the Sub Template as "DeptSubtemps".
In your main RTF template include the following commands:

<?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 will be determined based on the value of DeptName. For more information on CHOOSE statements in RTF templates, see 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 will perform the interest calculation on the data in this report and pass the result back to the main template. The subtemplate will accommodate the possibility that multiple reports that call this functionality may have different tag names for the components of the formula.

Assume 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>

In an RTF file, create a template declaration called "calcInterest". In this subtemplate you will define a parameter for each of the elements (principal, interest rate, and years) in the formula. Note that you must set the default value for each parameter.
```
<?template:calcInterest?>
   <?param:principal;0?>
   <?param:intRate;0?>
   <?param:years;0?>
   <?number($principal) * number($intRate) * number($years)?>
<?end template?>
```
Create a Sub Template in the catalog in the following location:

Shared Folders/Subtemplates

Upload the RTF file and save the Sub Template as "calculations".
In your main template enter the following to import the subtemplate:
```
<?import:xdoxsl:///Subtemplates/calculations.xsb?>
```
In the location where you want the results of the calculation to display, enter the following in a BI Publisher field:
```
<?call@inlines:calcInterest?>
   <?with-param:principal;./LOAN_AMOUNT?>
   <?with-param:intRate;./INTEREST_RATE?>
   <?with-param:years;./NO_OF_YEARS?>
<?end call?>      
```
Note the use of the @inlines command here. This is optional. The @inlines command forces the results to be rendered inline at the location in the template where the call to the subtemplate is made. Use this feature, for example, if you want to keep the results on the same line as a string of text that precedes the call.

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 Sub Template definition and assign the appropriate locale. These will display in the Templates region, as shown in the following figure:

the picture is described in the document text

Or you can generate an XLIFF (.xlf) file of the translatable strings, translate the strings, and upload the translated file. These will display in the Translations region, as shown in the following figure:

the picture is described in the document text

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 will be extracted and included in the larger catalog translation file. When the catalog translation file is uploaded to BI Publisher, the appropriate translations from the catalog file will display in the Translations region of the Sub Template definition.

For more information on translations, see the section Translating Reports and Catalog Objects.