Creating Report Templates

This chapter discusses how to:

Select report template type.
Use RTF templates.
Use PDF templates.

Selecting Report Template Type

Template design involves the construction of a report’s layout in a template file and is dependent upon what the core Oracle XML Publisher engines accept for processing.

This section provides an overview of report templates and discusses considerations for templates.

Understanding Report Templates

The nature of the data plays a role in the selection of a template.

Note. Internet Explorer does not have native support for svg graphics, a SVGViewer must be installed in order to see charts in Internet Explorer. SVGViewer is available for free download on Adobe web site - http://www.adobe.com/svg/viewer/install/ .

There are different considerations when it comes to choosing template types for your reports, below is a list of supported template types along with descriptions and guidelines:

Template Type	Description
PDF Template	Reports are pre-rendered PDF forms that are simply filled with data at runtime. The mapping between xml data source elements and PDF form fields is implemented using a simple algorithm that does not support nested structures such as multi-value fields. This limitation is mainly because of the static nature of PDF forms. Suitable when you have existing PDF forms that you need to use to generate reports, such as government forms. Generally faster than RTF templates since there is no runtime rendering involved. All element names in the schema must be unique, since there will be one-to-one mapping between xml elements and PDF form fields. The low level repeated elements should be a single element (not siblings). For example: AllPaychecks -> EmplID,Earnings,Taxes, Benefits In this example, EmplID, Earnings, Taxes and Benefits (the low level elements) are siblings. The PDF processor will not be able to produce a report that has low level sibling elements. To correct this situation, the User could modify the schema to combine the siblings into a compound type like Paycheck, which would be the child of AllPaychecks. The resulting structure will look like: AllPaychecks -> Paycheck(EmplID, Earnings, Taxes, Benefits) Use PDF templates when: You already have PDF templates that you must use (e.g. government forms). You have simple form-based reporting requirements with no complex formatting (i.e. no charting, dynamic tables, dynamic repeated fields and so forth.
RTF Template	RTF engine is the core of XMLP, it is based on the W3C XSL-FO standard and it is the fastest, most scalable implementation in the world today. Reports are fully rendered reports, which means, the actual PDF output is generated at runtime using XSLFO technology. Report designers have full control on output formatting and can incorporate charts, dynamic tables, conditional formatting and so forth. Reports are generally slower than PDF based reports since they involve real-time output rendering. For bursting, XML schema should have a single repeated element (paycheck, emplId, an so forth) on a second level (child of the root element).
eText	eText templates are RTF-based templates that are used to generate flat file text output that can be transmitted to a bank or other customer for Electronic Funds Transfer (EFT) or Electronic Data Interchange (EDI). Because the output is intended for electronic communication, these templates must follow specific format instructions for data placement. See Oracle XML Publisher Core Components Guide, eText Templates.
XSL Templates	For more complex design requirements, a number of XSL and XSL-FO elements are supported for use with your XSL templates. See Oracle XML Publisher Core Components Guide, XSL, SQL, and XSL-FO Support.

Note. Sample report templates are bundled with the XML Publisher Desktop, and available in <Installation Directory>\XML Publisher Desktop\samples.

Using RTF Templates

RTF templates support most XSL functionality and can be designed with robust processing and formatting code.

This section discusses how to:

Create RTF templates.
Incorporate sub-templates.
Include images.
Change default template font.

Creating RTF Templates

To create an RTF template using Microsoft Word:

Download the delivered XML Publisher Template Builder plug-in for offline template design on the Reporting Tools, XML Publisher, Setup, Design Helper page to facilitate the insertion of application data tags into your RTF templates.

The XML Publisher Template Builder is an extension to Microsoft Word that simplifies the development of RTF templates. While the Template Builder is not required to create RTF templates, it provides many automated functions that may increase your productivity.

Note. You can choose to automatically view the Word Template Builder Tutorial File, Word Template Builder Tutorial.doc, upon installing the plug-in. This document offers a quick and informative tutorial of the Template Builder.

The Word Template Builder Tutorial.doc is located in the \\Word Template Builder\doc directory of the folder where Oracle XML Publisher Desktop, XML Publisher Template Builder plug-in, was installed.

Sample report templates are available in <Installation Directory>\XML Publisher Desktop\samples.
Download the XML schema and sample data files by clicking the Data Schema and Sample Data links on the Reporting Tools, XML Publisher, Report Definition page for a specified query.
Load the schema and sample data into the document by selecting Data, Load Schema or Load XML Data from within the Microsoft Word Template Builder tool bar menu.
Design your template in the RTF document.

By using the downloaded schema or XML sample data, you can insert the data field tags into your template rather than manually typing XSL-formatted tags.

You can preview the template output with the sample XML data by selecting either Adobe Acrobat Reader (PDF), Microsoft Word file (RTF), Microsoft EXCEL (EXCEL), or a browser (HTML) from the Microsoft Word Preview menu.
Upload the completed template into the report definition by clicking the Upload button on the Reporting Tools, XML Publisher, Report Definition, Template page.

Note. Your data source xml structure should be designed to be as close as possible to the actual report template structure; this will improve runtime performance by preventing unnecessary XSL transformation. This is particularly applicable for reports with complex data structures and very large file sizes.

See Oracle XML Publisher Core Components Guide, Creating an RTF Template.

See “\\Word Template Builder\doc\Word Template Builder Tutorial.doc.”

See Working with Template Design Helpers, Creating Report Definitions.

Incorporating Sub-templates

When designing a template, you can incorporate one or more sub-templates into your primary template.

Specific syntax must be used to:

Create sub-templates.
Import sub-templates.
Call sub-templates.

See Using the Content Library to Maintain Sub-templates.

Creating Sub-templates

Within a single sub-template file, multiple sub-template components can be available. Start and end template indicators must exist to distinguish those various components.

<?template:component_name?>
<?end template?>

For example, syntax of a sub-template file containing two components could be:

<?template:peoplesoft?>
Pleasanton Campus
500 Oracle Lane
Pleasanton, CA  94488 
<?end template?>

<?template:logo2x.5?>
 Oracle_Logo
<?end template?>

where <?template:peoplesoft?> is the start template indicator of the component peoplesoft and <?template:logo2x.5?> is the start template indicator of the component logo2x.5. Each <?end template?> tag indicates the end of its respective component.

Importing Sub-templates

To import a sub-template file that is stored in the Content Library, the following syntax must be placed at the top of the primary template file:

<?import:psxmlp://sub-template_NAME?>

where sub-template_NAME is the registered sub-template ID in the Content Library, for example: <?import:psxmlp://STDHEADER?>. This syntax must be in Normal text.

Note. The sub-template reference is only defined in the RTF template. The sub-template must be defined in Content Library, however the relationship to templates using the sub-template is not defined in the database. Developers must be aware of the sub-template relationships when modifying the RTF sub-template.

See Using the Content Library to Maintain Sub-templates.

Calling Sub-templates

The following syntax must be placed in the primary template file in the location where the desired text or XSL instructions from the sub-template file should appear:

<?call-template:peoplesoft?>

where peoplesoft is the name of the component that you want to use in the sub-template file.

Note. Primary templates calling nonexistent or inactive sub-templates presents an error indicating the reason for the problem. This error information is incorporated into Process Scheduler error handling as well as into online viewing or previewing of the report.

See Running XML Publisher PeopleSoft Query Reports.

Testing Sub-template in Microsoft Word

You should test your template and sub-template using Template Builder before uploading to PeopleTools, to make your sub-template is accessible to your template on the file system.

Use the following syntax when importing:

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

Notice the triple slashes and the use of the actual file name instead of template ID.

When your design is complete, you can change the import statement back to make the sub-template available to the main template in PeopleTools environment:

Including Images

XML Publisher supports a number of methods for including images in your reports:

Inserting images.
Referencing images.
Importing images.

Inserting Images

To directly insert a .jpg, .gif, or .png image file into a template:

Select Insert->Picture->From File while the template is open in Microsoft Word.
Select the desired .jpg, .gif, or .png file to insert into the template.
Save the template.

Note. It is advised to use the Microsoft Word Insert menu option to insert the image, as the additional properties that need to be set for the RTF template to correctly generate reports with those images are automatically set by using this method. Additionally, dragging and dropping an image onto a template creates a link to the local machine being used and may cause problems when the report is generated.

Referencing Images

To reference images with a URL:

Insert a dummy image into the template in the appropriate location.
In the Format Picture dialog box in Microsoft Word, select the Web tab.

Enter the following syntax in the Alternative Text region to reference the URL image: url:{‘http://image location’}.

For example: url:{‘http://www.oracle.com/images/ora_logo.gif’}.

Note. The user has to be online to access the image referenced in the URL.

Importing Images

To import an image from a sub-template file:

Embed the .jpg, .gif or .png into the sub-template file.

For example,
```
<?template:logo2x.5?>
 Oracle_Logo
<?end template?>
```
where Oracle_Logo is the actual .jpg, .gif, or .png.
Import the sub-template file that includes the image by including the following syntax at the top of the primary template file:
```
<?import:psxmlp://sub-template_NAME?>
```
where sub-template_NAME is the registered sub-template ID in the Content Library.
Insert a dummy image into the primary template in the appropriate location.
Add the calling details in the Format Picture dialog box in Microsoft Word using the syntax:
```
<?call-template:logo2x.5?>
```
where logo2x.5 is the name of the component that contains the image in the sub-template file.

See Incorporating Sub-templates.

Changing Default Template Font

The output report from RTF template uses template level default fonts for empty report spaces and empty table cells. If default font size does not match font height used in a template, a final report could look different from user expectations. In this case the user can change template default font either in design time or runtime:

Design time

Set the xdo.cfg for the font, for example set default font for a specific report to be Helvetica, size is 8: <property name="rtf-output-default-font">Helvetica:8</property>

Runtime

Use PeopleCode to set the font. for example set default font for a specific report to be Times New Roman with height 10 :

Local PSXP_ENGINE:FOProcessor  &oFOProcessor = create PSXP_ENGINE:FOProcessor();

&oFOProcessor.ConfProp = create PSXP_ENGINE:Properties();

 If Not &oFOProcessor.ConfProp.setProperty("rtf-output-default-font", "Times New Roman:10") Then
         Return False;
 End-If;

Using PDF Templates

This section discusses:

Working with PDF templates.
Creating PDF templates.
Mapping data tags.

See Associating Templates.

Working with PDF Templates

PDF templates do not require a plug-in for offline template design. A mapping feature for XML data element tags is enabled when the PDF template file is uploaded into the Reporting Tools, XML Publisher, Report Definition, Template page. The XML Publisher PDF mapping functionality allows you to match existing form fields in a PDF template with data schema field tags.

If you are not using a third party PDF template, you don't need to map data tags if you create PDF template field names and XML data tags that are the same to begin with. You can also change the PDF template field names to match your XML data tags.

The following guidelines need to be adhered to when working with PDF templates whether or not you are mapping PDF template fields and tags:

The PDF document must allow editing.

Check the Security setting in the File, Document Properties, Summary page.
Files must be Adobe Acrobat 5.0 compatible.

If you are using a later version of Adobe Acrobat, go to File, Reduce File Size and select the Make Compatible with: Acrobat 5.0 and later option.
Files must have form fields for the placement of application data, with each field tag being unique.

If no form fields exist, use the Adobe Professional version to add field tags. If there are duplicate tags or non-unique tags in forms obtained from third parties, use Adobe Professional to update the tags.
Files should not have embedded javascript.

XML Publisher removes it during the course of the Map Enablement function when the Generate button on the Reporting Tools, XML Publisher, Report Definition, Template page is selected.

Processing PDF Templates

The Oracle XML Publisher Core Engine adheres to the following rules when processing PDF templates:

The hierarchy of the XML is ignored.
The search for the tag that matches the field name starts at the end of the XML file.
The first match of the tag is used for the field value.
If the tag is not found, it looks at the map file (if provided).

This means that even if the form is mapped, when there is a tag in the XML data that matches the PDF template form field tag, it has priority over the map for placing the data.

Creating PDF Templates

To create a PDF template without mapping tags using Adobe Acrobat:

Design your template in the PDF document as documented in the Oracle XML Publisher Core Components Guide.

Be sure that the PDF template field names match the XML data tags.
Upload the completed template into the Report Definition by clicking the Upload button on the Reporting Tools, XML Publisher, Report Definition, Template page.

Note. XML Publisher supports Adobe Acrobat 5.0 (PDF specification version 1.4). If you are using a later version of Adobe Acrobat, use the File, Reduce File Size option to save your file as Adobe Acrobat 5.0 compatible.

See Oracle XML Publisher Core Components Guide, Creating a PDF Template.

Mapping Data Tags

Third parties most often supply PDF templates where the form fields already exist inside the form template. In order for the XML data element tags to know where they should print within the PDF template, a mapping is required between the field elements from the data source and the form field elements in the PDF template. By taking a PDF form with editable form fields and mapping those fields to XML schema fields generated by PeopleSoft Query or from any other data source’s XML schema, the template is ready for use by XML Publisher.

Prior to being able to perform this mapping, some XML Publisher-specific pre-processing of the file is required. This processing requires the existence of an OPEN schema and the report’s data source. Adobe Standard or above and version 6 or above is required for the template mapping. In the event that the PDF form does not have form fields, the form field and tags can be inserted using the Designer or Professional versions of Adobe. The form field tags can then be mapped to the schema tags.

To create a PDF template by mapping data element tags using Adobe Acrobat:

Upload the PDF template file to be mapped by clicking the template file Upload button on the Reporting Tools, XML Publisher, Report Definition, Template page.
Generate the file to be mapped by clicking the map file Generate button.

Generate creates a map-enabled PDF with the letter m added at the end of the file, for example if the original file is template.pdf, the mapped file will be templatem.pdf and allows you to access the data tags by placing schema and sample data into the PDF file.
Visually map the data tags to the form’s field tags.

The mapping exercise is performed offline within the Adobe Acrobat application.
Once complete, save the file locally with a new name.

Some indication of mapping should be included in the name to distinguish it from the unmapped file. For example, i9m.pdf.
Upload the mapped PDF file on the Reporting Tools, XML Publisher, Report Definition, Template page by selecting the map file Upload button.

When uploaded to the server, the mapping information is stored along with the PDF form template.

Note. If the PDF template’s field names are the same as the data source's data tag names, then no mapping or uploading of a map file is required.

Note. PDF file security has to allow editing and saving for the mapping to be completed. The ability to perform these functions depends on the Adobe version you are working with.

Note. If no map file exists for your PDF file, selecting the Preview button on the Reporting Tools, XML Publisher, Report Definition, Template page won't show any data.

XML Publisher and Adobe

XML Publisher provides the following features within Adobe:

A visual indication of the PDF form fields that have been mapped.

A dark blue outline displays around the mapped form fields.
Display of the mapped field tag name when the cursor hovers over the PDF form field.
A pop-up dialogue containing a schema tag list that you can select from to insert the field tag when you click on the PDF form field.
Preparation of the PDF form for uploading to the report definition when you save the file locally by doing a File, Save.

This is an example: