It is likely that you will design several templates that contain common components or functionality, such as address formatting or string formatting functions. Rather than replicate this functionality in every template, you can place the common components in a separate template that can be called at runtime by the other templates. The template containing the common components is a "subtemplate."

If your template requires complex calculations or conditional formatting of tabular data, you can also use a subtemplate for these instructions to keep the primary template simple for your users to understand.

Using a subtemplate consists of four steps:

1. Create the RTF file containing the common components or processing instructions. This is your subtemplate.

2. Register the subtemplate in the Template Manager.

3. Enter the import syntax in the calling or "primary" template to import the subtemplate.

4. Enter the call-template syntax in the primary template in the position that you want the subtemplate contents to render.

Create the Subtemplate RTF File

Enter the components or instructions in an RTF file. To define this file as a subtemplate, enclose the contents in the following tags:

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

where

template_name is the name you choose for the subtemplate.

Note that in a single file, you can have multiple <?template:template_name?><?end template?> entries, to mark different "subtemplates" or segments you would like to include in other files.

Register the Subtemplate RTF File in the Template Manager

Register the subtemplate RTF file in the Template Manager. To define it as a subtemplate, select Subtemplate = YES.

For more information about the Template Manager, see Creating the Template.

Enter the Import Syntax in the Primary Template

Import the subtemplate to the primary template by entering the following syntax in the primary template. The import syntax tells the XML Publisher engine where to find the subtemplate RTF in the Template Manager. This syntax may be entered anywhere in the template prior to the call-template syntax:

<?import:xdo://APPCODE.TEMPLATE_CODE.lang.TERR?>

where

APPCODE is the Application code you assigned to the subtemplate in the Template Manager. For example, if you associated this template with the Receivables application, enter "AR".

TEMPLATE_CODE is the template Code you assigned to the subtemplate in the Template Manager. For example, AR_CommonComponents.

lang is the two-letter ISO 639 language code for the template language you specified for the subtemplate in the Template Manager (for example, English is "en"). This entry must be lowercase.

TERR is the two-letter ISO 3166 country code for the template territory you specified for the subtemplate in the Template Manager (for example, United States of America is "US"). This entry must be uppercase.

Add the call-template Syntax to Your Primary Template

Use the call-template command to render the contents of the subtemplate in the position specified, as follows:

<?call-template:template_name?>

where

template_name is the name you assigned to the subtemplate in Step 1.

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.

The common components subtemplate will contain the following:

<?template:MyAddress?>
R&G Corporation
500 Marine Parkway
Redwood Shores, CA 94065
<?end template?>

This defines the string in a subtemplate called MyAddress. Save this template as RTF and add it to the Template Manager using the following criteria:

• Application Code: CUSTOM

• Template Code: COMMONCOMPONENTS

• Language: English

• Territory: United States of America

• Select "Yes" for Subtemplate

Now this subtemplate and any functions therein can be referenced from any other template.

To call this subtemplate from another template, first import it by inserting the following syntax at the top of the calling template:

<?import:xdo://CUSTOM.COMMONCOMPONENTS.en.US?>

At the position in the template where you want to display the address, enter:

<?call-template:MyAddress?>

At runtime the contents of the MyAddress subtemplate will be fetched and rendered in the layout of the calling 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.

Testing Your Subtemplate

If have the XML Publisher Desktop Template Builder and Template Viewer installed, you can preview the template and subtemplate combination before uploading them to the Template Manager. To test from your local environment, you must alter the import template syntax to enable the XML Publisher processor to locate the subtemplate file.

To test, enter the import template syntax as follows:

<?import:file:path to subtemplate file?>

where path to subtemplate file is the location in your local environment where the subtemplate file is located. For example:

<?import:file:C:///Template_Directory/subtemplate_file.rtf?>

Now when you select the Preview option in the Template Builder, the XML Publisher processor can locate your subtemplate and render it from your local environment.

Note that before you upload the primary template to the Template Manager you must change the import syntax as specified in the step Enter the Import Syntax in the Primary Template.