Oracle BI Publisher Blog

I have seen a few questions around sub templates on the forum recently. Using subtemplates is a very powerful way of making your life as a template developer much easier, if you have a piece of formatting functionality that you intend to use across multiple templates then break it out as a sub template you can then benefit from write once - maintain in one place. This also applies to headers and footers, most if not all of you will have an 'organization' header and footer that you need to have on all of your documents - again just create a sub template and reference it from all your top level templates, you can even pass parameters to the header/footer formatting to 'personalize' the header for each template but still manage only a single sub template.

RTF or XSL

You can use either RTF or pure XSL as a subtemplate. RTF is great if you have some visual formatting you need to do - much easier to develop using MSWord than writing XSL. XSL has its place thou, if you have some heavy lifting to do on the data to format it i.e. calculations, etc then XSL is the way to go.

Templates and functions ...
Its a little confusing when starting out with XSL. The complete formatting file is called a 'template' and the formatting functions within a subtemplate are also called templates ... just think about them as functions. You pass the function some object and it returns the modified object.

A Quick Example ...
Lets assume we want a common header and footer for our report outputs, we have a logo, data stamp, etc and we want to put the report name into it too. The report name is going to have to be dynamic and passed to the sub-template at runtime, we can achieve this because XSL lets us pass parameters around in the template call.  

So we have a sub template looking like the following, I have put in the raw commands rather than formfields to make it easier to see whats going on:



A you can see we have the template declaration:
<?template:Header?>
<?param:ReportName;string('My Report')?>

This declares a template called header and it is expecting a parameter called 'ReportName', if it is not populated at runtime then the default, 'My Report' will appear (this is not mandatory). The footer template is declared in a similar fashion.

In our calling template we will have something like:
  <?call@inlines:Header?>
   <?with-param:ReportName;string('Employee Report')?>
  <?end call?>

In the MSWord header of our template, this is calling the Header template and passing the parameter 'ReportName' with the value 'Employee Report', this could equally be an element name if you extracted the report name in the XML data. In the bdy of the template we need to declare that we want to use the sub template in this main template, so we will have a declaration:

<?import:file:///C:/temp/HeaderFooter.rtf?>

This brings up another interesting question for EBS template developers, how do I test my sub template without deploying it to the template manager. Well the import statement supports a URI reference so we can either use the file URI or a UR to reference our sub template. In this case the subtemplate is in the c:/temp directory. Very useful when you want to test. For EBS developers, remember to change this to the 'xdo:' URI format prior to deploying.  
So when we run the main template it will call the Header template and pass in the report name i.e. Employee Report to the subtemplate and the full header will be passed back to the calling template including the logo, timestamp, etc.

So sub templates need a little effort to set up but the benefits going forward far outweigh the cost. Write it once and deploy it everywhere and maintain it in one place going forward ... when management decide to change the company branding overnight you'll thank your lucky stars you used sub templates!