12 Understanding Subtemplates

This topic describes concepts for using subtemplates. A subtemplate is a piece of formatting functionality that can be defined once and used multiple times within a single layout template or across multiple layout template files.

Topics:

For information on designing an RTF subtemplate, see Designing RTF Subtemplates. For information on designing an XSL subtemplate, see Designing XSL Subtemplates.

What is a Subtemplate?

A subtemplate is a piece of formatting functionality that can be defined once and used multiple times within a single layout template or across multiple layout template files.

This piece of formatting can be in an RTF file format or an XSL file format. RTF subtemplates are easy to design as you can use Microsoft Word native features. XSL subtemplates can be used for complex layout and data requirements.

Some common uses for subtemplates include:

  • Reusing a common layout or component (such as a header, footer, or address block)

  • Handling parameterized layouts

  • Handling dynamic or conditional layouts

  • Handling lengthy calculations or reusing formulae

About 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 subtemplate object in the Catalog, can be called from within another RTF Template.

About XSL Subtemplates

An XSL subtemplate is an XSL file that contains formatting or processing commands in XSL for the BI Publisher formatting engine to execute. Use an XSL template to include complex calculations or formatting instructions not supported by the RTF standard.

This XSL file, when uploaded to BI Publisher as a Subtemplate object in the Catalog, can be called from within an RTF Template.

Supported Locations for Subtemplates

It is recommended that you upload subtemplates to the BI Publisher catalog.

The catalog is the most secure location.

For compatibility with older versions of BI Publisher, it is also possible to call a subtemplate that resides in a file on the local server, or on a different server (that can be accessed by HTTP protocol). Using one of these methods requires specific import syntax and server settings to allow the communication. See Calling a Subtemplate from an External Source for more information.

Testing Subtemplates from the Desktop

If you have the BI Publisher Template Builder installed, you can preview the template and subtemplate combination before uploading them to the BI Publisher catalog.

To test from your local environment, you must alter the import template syntax to enable the BI Publisher processor to locate the subtemplate file on a local directory. To test, enter the import template syntax as follows:

<?import:file:{local_template_path}?>

For example:

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

or for an XSL subtemplate file:

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

You can then select the Preview option in the Template Builder and the BI Publisher processor can locate the subtemplate and render it from your local environment.

Note that before you upload the primary template to the BI Publisher catalog, you must change the import syntax to point to the appropriate location in the catalog.

Uploading a Sub Template

You can upload one or more sub templates for use with BI Publisher.

To upload a subtemplate file:

  1. On the global header click New and then click Sub Template. This launches an untitled Sub Template page.
  2. In the Templates region, click Upload.
  3. In the Upload Template File dialog, select the subtemplate file for upload.

    • Type: Select rtf for RTF subtemplate files or xsl for XSL subtemplate files.

    • Locale: Select the appropriate locale for the subtemplate file.

  4. Click Upload.

    The subtemplate file is displayed in the Templates region as the locale name that you selected (for example: English).

  5. Click Save. In the Save As dialog choose the catalog folder in which to save the Sub Template. Enter the Name and click Save. The following illustration shows a Sub Template named "My Subtemplate".
  6. (RTF Sub Templates only) If you are uploading multiple localized files, then select the file that is to be used as the default. For more information on localization of template files, see Adding Translations to an RTF Subtemplate.

    Note:

    You may upload only one RTF file per locale to a Sub Template definition. If you upload additional template files to this Sub Template, each file is automatically named as the locale regardless of the name that you give the file before upload.

    Note:

    Translations are not supported for XSL Sub Templates.

Note that the Sub Template object is saved with the extension ".xsb". You use the Name that you choose here with the .xsb extension when you import the Sub Template object (for example: MySubtemplate.xsb).

Calling a Subtemplate from an External Source

This section describes how to call a subtemplate that resides outside the catalog.

Note:

These instructions are provided for backward compatibility only. It is recommended that you place subtemplates in the catalog.

Note that localization is not supported for subtemplates that are maintained outside the catalog.

Importing a Subtemplate Outside the Catalog over HTTP or FTP

Use a standard protocol, such as http or ftp and enter the import statement as shown here.

<?import:http//myhost:8080/subtemplate.rtf?>

Importing Subtemplates Outside the Catalog on the Same Server

If the subtemplate is located on the server, but not in the BI Publisher catalog, then enter this.

<?import:file://{template_path}?>

where

template_path is the path to the subtemplate file on the server

For example:

<?import:file://c:/Folder/mySubtemplate.rtf?>

Required Settings To Run Sub Templates Stored Outside the Catalog

To run sub templates outside the catalog you must configure the disable external references property.

Using sub templates requires the following FO processing configuration property setting for the report:

Disable external references: Must be set to False