Creating Report Templates

This chapter provides an overview of report template types and discusses how to:

• Use RTF templates.

• Use PDF templates.

See Also

Oracle BI Publisher Core Components Guide.

XML Publisher Classes

Understanding Report Template Types

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

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; an SVGViewer must be installed for you to see charts in Internet Explorer. SVGViewer is available for free download on the Adobe website at http://www.adobe.com/svg/viewer/install/.

The following table lists and describes supported template types and provides guidelines for you to consider:

Note. Sample report templates are bundled with the BI Publisher Desktop, and available in <Installation Directory>\BI 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.

• Use drilling URL in RTF template.

Creating RTF Templates

To create an RTF template using Microsoft Word:

1. Download the delivered BI 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 BI 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, Template Builder for Word Tutorial.doc, upon installing the plug-in. This document offers a quick and informative tutorial of the Template Builder.
   
   The Template Builder for Word Tutorial.doc is located in the \Template Builder for Word\doc directory of the folder where Oracle BI Publisher Desktop, BI Publisher Template Builder plug-in, was installed.
   
   Sample report templates are available in <Installation Directory>\BI Publisher Desktop\samples.

2. Download the XML sample data file by clicking the Sample Data link on the Reporting Tools, XML Publisher, Report Definition page for a specified query.

3. Load the sample data into the document by selecting Data, Load XML Data from the Microsoft Word Template Builder tool bar menu.

4. Design your template in the RTF document.

   By using the downloaded 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 from the Oracle BI Publisher menu using Preview Template or select Preview from the Template Builder toolbar.

5. 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 groupings used for in the actual report template structure; this improves runtime performance by preventing unnecessary XSL transformation. This is particularly applicable for reports with complex data structures and very large file sizes.

See Oracle BI 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.

You must use specific syntax to:

• Create sub-templates.

• Import sub-templates.

• Call sub-templates.

See Maintaining 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 these 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, place 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, for example: <?import:psxmlp://STDHEADER?>. This syntax must be in Normal text.

Note. The sub-template reference is defined only 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 Maintaining Sub-Templates.

Calling Sub-Templates

Place the following syntax 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?>

In the preceding sample code 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 cause an error message to be issued 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 a 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

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

• Inserting images.

• Importing images.

Inserting Images

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

1. Select Insert, Picture, From File while the template is open in Microsoft Word.

2. Select the desired .jpg, .gif, or .png file to insert into the template.

3. Save the template.

Note. Oracle recommends that you use the Microsoft Word Insert menu option to insert the image, because the additional properties that you need to set for the RTF template to correctly generate reports with those images are automatically set by means of 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.

Importing Images

To import an image from a sub-template file:

1. 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.

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

   In this code sample, sub-template_NAME is the registered sub-template ID in the Content Library.

3. Add the calling details in the primary template at the appropriate location using the following syntax:

   <?call-template:logo2x.5?>

   In this code sample, 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 the default font size does not match the font height used in a template, a final report could look different from user expectations. In this case, the user can change the template default font either in design time or runtime:

• Design time

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

• Runtime

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

  &asPropName = CreateArrayRept("", 0);
  &asPropValue = CreateArrayRept("", 0);            
  &asPropName.Push(""rtf-output-default-font");
  &asPropValue.Push(""Times New Roman:10");
  &oRptDefn.SetRuntimeProperties(&asPropName, &asPropValue);

Using Drilling URL in RTF Template

Drilling URLs are supported in XML Publisher reports with a data source of PS Query or Connected Query.

Note. Drilling URLs are supported only in RTF templates.

To use a drilling URL in a XML Publisher report:

1. Create the query with the drilling URL defined as a field.

   See Drilling URL in Oracle PeopleSoft Query.

2. Create an RTF template.

3. In the RTF template map one or more fields to the fields that contain drilling URL.

   • Highlight the field where you want to place the drilling URL.

   • Select Insert (from the Word menu), Hyperlink or use Ctrl+K.

   • In the Insert Hyperlink dialog box, enter the URL link in Address field.

     Each URL link should be defined as {URL_FIELD}, where URL_FIELD is the unique field name for the expression that contains a specific drilling URL.

   • Use the Target Frame push button to select how this URL link will be opened, either in the same window or in the new window

     Note. The URL value does not need to be added to the report, as long as the unique field name (data file that contains the URL) is mapped to a field in the report.

4. If the XML Publisher report is run in Process Scheduler using an application engine program, you will need to add additional code to identify the process instance for the application engine program before processing the report. The process instance can be retrieved from the state record PSXPQRYRPT_AET. This call is needed to set a drilling URL during Query or Connected Query execution.

   &ProcessInstance=PSXPQRYRPT_AET.PROCESS_INSTANCE;
   &oRptDefn.ProcessInstance = &ProcessInstance;
   &oRptDefn.ProcessReport("", "", %Date, "");

5. When you click the drilling URL in the report depending on the drilling URL type, one of the following occurs:

   • For Query URL, the Query results are displayed.

   • For Component URL, the appropriate PeopleSoft page is opened.

   • For External URL, the external page is opened.

See Also

Oracle Business Intelligence Publisher User’s Guide, Creating an RTF template, Template Features, Hyperlinks

Using PDF Templates

This section discusses how to:

• Work with PDF templates.

• Create PDF templates.

• Map data tags.

See Associating Templates.

Working with PDF Templates

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

You only need to do mapping, if the form field names in the PDF template do not match the tag names in the XML data. This is usually the case when you are using a third-party PDF template (such as government form) and when it is not easy to customize the tag names in XML data to match the PDF form fields.

Observe the following guidelines when working with PDF templates regardless of whether you are mapping PDF template fields or 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, select File (or Document — depending on the version of Adobe), Reduce File Size and select the Acrobat 5.0 and later value in the Make Compatible with: 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 duplicate tags or nonunique tags are 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 BI Publisher Core Engine adheres to the following rules when processing PDF templates:

• 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, the Oracle BI Publisher Core Engine looks at the map file (if provided).

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

Using Full Path Mapping

The PeopleSoft implementation for PDF mapping supports full path mapping. Full path mapping is not supported in the BIP Server. Full path mapping should only be used when you have no control on the structure and names of your XML data tags. For you to use full path mapping, the data source definition must include sample XML with no schema.

Note. Full path mapping is available only for PeopleTools 8.50 and later. It is not backward compatible.

Creating PDF Templates

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

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

   Be sure that the PDF template field names match the XML data tags.

2. Upload the completed template into the Report Definition by clicking the Upload button on the Reporting Tools, XML Publisher, Report Definition, Template page.

Note. BI 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 BI Publisher Core Components Guide, Creating a PDF Template.

Mapping Data Tags

Third parties most often supply PDF templates in which the form fields already exist inside the form template. 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. Once a PDF form with editable form fields is mapped to the XML sample data fields, 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 sample data 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 sample data tags.

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

1. 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.

2. If you are using full path mapping, select the Full Path Mapping check box.

3. Generate the file to be mapped by clicking the map file Generate button.

   Generate creates a map-enabled PDF, with the following naming convention. The plug-in enables you to access the data tags by embedding a JavaScript plug-in inside the PDF template.

   • A dash and the letter m added at the end of the file. For example, if the original file is template.pdf, the mapped file will be template-m.pdf if path mapping is not selected.

   • A dash and the letter mfp added at the end of the file. For example, if the original file is template.pdf, the mapped file will be template-mfp.pdf if path mapping is not selected.

4. Visually map the data tags to the form’s field tags.

   The mapping exercise is performed offline within the Adobe Acrobat application.

5. Save the file.

   The generated file name indicates the type of mapping, as previously defined in step 2.

6. 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 in the database 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 that 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 will not show any data because the form fields names do not match XML data tag names.

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 appears around the mapped form fields.

• Display of the mapped field tag name when the cursor hovers over the PDF form field.

• A pop-up dialog box containing an XML tag list that you can select from to insert the field tag when you click 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.