When to Use RTF Subtemplates

Reuse 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 Display 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 Publisher to apply a different <?template?> defined in the subtemplate file.

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

To call the sub template with the appropriate address format:

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 the 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 is properly applied, depending on the value of COUNTRY_CODE in the data.

Conditionally Display 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.

You cannot conditionalize the import statement for the subtemplate file.

Example

Assume in the report data model that you've 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're 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.

To display the 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 the 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 is determined based on the value of DeptName. For more information on CHOOSE statements in RTF templates, see Insert Choose Statements.

Handle 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've 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>

To set up a sub template to contain a formula for calculating interest:

In an RTF file, create a template declaration called calcInterest. In this sub template 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 the main template, enter the following to import the sub template:
```
<?import:xdoxsl:///Subtemplates/calculations.xsb?>
```
In the location where you want the results of the calculation to display, enter the following in a 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 sub template 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.