Using Stationery Template Editor

Template Preparation and Sample Data

After selecting to create or update a stationery template two files (*.rtf and *.xml) are downloaded to a folder on your workstation.

Note:

When creating a new stationery template you must first rename the sample*.rtf to something different. You cannot upload a customized template with the filename sample*.rtf.

Open RTF file

Navigate to the download folder and open the RTF template file using Microsoft Word; either double-click the file in Windows Explorer or launch Microsoft Word and the use the File | Open menu from within Word.

Load Sample XML Data File

The sample data file consists of data element (XML elements) available for inclusion in the layout of the stationery template. 

1. Click the BI Publisher tab on the toolbar and click Sample XML.

2. Navigate to the folder where the sample XML file was downloaded to.

3. Select the file and click Open.

Note:

The Oracle BI Publisher toolbar appears in Microsoft Word after installation of the Oracle BI Publisher software. If the toolbar does not appear automatically, select View, select Toolbars, and then select Template Builder to add it to the existing toolbar display. Also ensure that BI Publisher add-in is enabled in COM Add-Ins (File, Options, Add-Ins, Manage COM Add-Ins, Go)

Figure 9-1 Load Sample XML Data

The XML data file will always be named sample_xxxx, corresponding to the type of template you are customizing. For example, if you are creating a confirmation letter template and you named the RTF file “email_confirmation,” you will not see a corresponding XML file. Rather, you would select and load the “sample_guest_confirmation.xml” , listing all the available elements for customization on the confirmation template.  Once the XML is selected, a “Data loaded successfully” message appears and informs you that the sample XML data is now loaded for use in customization.

Each tag set is an element. For example <RESERVATION_MADE_DATE_ISO>2020-12-12</RESERVATION_MADE_DATE_ISO> is the date the reservation was created. RESERVATION_MADE_DATE_ISO is the tag name. The data between the tags is the value of the element.  For example, the value of <RESERVATION_MADE_DATE_ISO> is a date 2020-12-12 (12th December 2020).

Note:

Sample XML files contain property details elements such as Property Code, <RESORT>, Property Name <RESORT_FULL_NAME>, Property Address <RESORT_FULL_ADDRESS>, Property Phone <RESORT_PHONE_NO> - ensuring one template can be shared across multiple properties.

Identifying Placeholders and Groups

The template content and layout must correspond to the content and hierarchy of the input XML file. Each data field in the template must map to an element in the XML file. Each group of repeating elements in the template must correspond to a parent-child relationship in the XML file.

To map the data fields you define placeholders. To designate the repeating elements, you define groups.

When you mark up the template design, you define placeholders for the XML elements. The placeholder maps the template report field to the XML element. At runtime the placeholder is replaced by the value of the element of the same name in the XML data file.

Using Placeholders

Each data field in the report template must correspond to an element in the XML file. When you mark up the template design, you define placeholders for the XML elements. The placeholder maps the template report field to the XML element. At runtime the placeholder is replaced by the value of the element of the same name in the XML data file.

Identifying Group of Repeating Elements

Stationery templates often contain groups of repeating fields; this occurs when data is fetched from multiple entities in a parent-child 1:many relationship. For the folio this applies to the posting details for one reservation. Fields that belong to one of the child entities are prefixed with a G_ to identify a repeating group of fields.  At runtime, BI Publisher loops through the occurrences of the element in the XML and outputs the data for all records within the group.

The following is the XML file that correspondence to a folio RTF template

Figure 9-2 Sample_folio.xml and Repeating Groups

Adding Markup to the Template Layout

BI Publisher converts the formatting that you apply in Microsoft Word to XSL-FO.

You add markup to create the mapping between the layout and the XML file and to include features that cannot be represented directly in the format.

The most basic markup elements are placeholders, to define the XML data elements; and groups, to define the repeating elements.

Creating Placeholders

The placeholder maps the template field to the XML element data field. At runtime the placeholder is replaced by the value of the element of the same name in the XML data file.

Enter placeholders in the document using the following syntax:

<?XML element tag name?>

The placeholder must match the XML element tag name exactly and is case sensitive.

There are two ways to insert placeholders in the document, as described in the following sections:

• Using the Basic RTF Method: Insert the placeholder syntax directly into the template document.

• Using the Form Field Method: Insert the placeholder syntax in Microsoft Word's Text Form Field Options window. This method allows you to maintain the appearance of the template.

• Using the Basic RTF Method

  1. Enter the placeholder syntax in the document where you want the XML data value to appear.

  2. Enter the element's XML tag name using the syntax:

     <?XML element tag name?>

     In the example, the template field "Reservation Made Date" maps to the XML element RESERVATION_MADE_DATE_ISO in the document, enter:

     <?RESERVATION_MADE_DATE_ISO?>

• Using the Form Field Method

  After the XML data file has been loaded use the 123 Field option on the BI Publisher toolbar tab to insert new fields in the template.

  Search and select the XML tag or field to add to the customizable report from the list of available fields. The tree of available fields is divided into the sections applicable to the report groupings, (for example, header, footer, body, and so on). You can add fields by selecting and dragging the element to the document or double clicking on a selected field from this list to insert at the current cursor location.

  Note:

  It is recommended that tables are used in your layout to keep the field positions static. When creating a new table in Word, be sure to set the AutoFit behavior to ‘AutoFit to Contents’ to avoid truncating fields larger than the actual cell size or resizing a cell to accommodate a field with a longer description than the display data. Refer to Microsoft Word Help (F1) for more details.

  Figure 9-3 Insert Form Field

  
  
  

Defining Groups

By defining a group, you notify BI Publisher that for each occurrence of an element, you want the included text and fields displayed.

At runtime, BI Publisher loops through the occurrences of the element and outputs the fields each time.

All sample stationery templates are preconfigured with the required groups for the corresponding XML data file.

For the folio, for each occurrence of G_DETAIL in the XML file, you want the template to display the child elements TRX_DATE, DESCRIPTION, REFERENCE_DISPLAYED, DEBIT, CREDIT and so on.

To designate a group of repeating fields, insert the grouping tags around the elements to repeat.

Insert the following tag before the first element

<?for-each:XML group element tag name?>

Insert the following tag after the final element:

<?end for-each?>

Inserting Images

There are two methods for inserting images into templates. For HTML email delivery (for example, confirmation letters), images must be published to a web server and the URL reference method must be used to reference the URL to the image. Referencing the image using the URL method provides a faster load/processing time for the template file since the file is smaller when the image is referenced rather than imbedded in the file.

Note:

There is a file size limit of 10MB for RTF templates.

Directly Inserting Images

For PDF output, images can be inserted directly into the RTF template.

Insert the jpg, gif, or png image directly in the template by selecting Insert and then selecting Pictures.

Reference Web Image URL

Reference to a web image means the image is fetched at runtime; the image can be updated at any time without the need to modify the template(s).

Include an alternative text link for an image.

To insert images with URL references:

1. Insert a dummy graphic into the layout in Word by selecting Insert and then selecting Pictures.

2. Right-click the image and select the Format Picture option and then click the Alt Text tab.

3. Enter the following syntax to reference the image location:

   URL:{'http://<image location>'}

Figure 9-4 Format Picture and Alt Text tab

For example, enter:

url:{' http://www.example.com/images/oracle_logo.gif'}

The dummy graphic (used as a place holder within the RTF) can be set to the required image size using picture tools.

At runtime, the placeholder graphic is replaced with the image available at the specified web address

Formatting Date and Numbers

BI Publisher supports two methods for specifying the number format.

• Microsoft Word's native number format mask.

• Oracle's format-number function.

BI Publisher supports three methods for specifying the date format

• Microsoft Word's native date format mask.

• Oracle's format-date function.

• Oracle's abstract date format masks. (Recommended for multilingual templates.)

For more information of formatting dates, numbers and currency values see Formatting Numbers, Dates, and Currencies.

Formatting Dates

In addition to pre-formatted dates in string format in the XML, all date fields are also available in canonical date/time format.

Canonical date fields are identified with the suffix _ISO in the element name and can be formatted to suit your needs:

To apply a MS Word format mask to a _ISO canonical date field:

1. Double click the date placeholder in the template.

2. Set Text to Display to a test date.

3. Set Type to Date.

4. Select a date format from the list.

5. Click OK.

Figure 9-5 Formatting Dates

Formatting Numbers

To apply a MS Word format mask to number fields:

1. Double click the number placeholder in the template.

2. Set Text to Display to a test number.

3. Set Type to Number.

4. Select a number format from the list.

5. Click OK.

Figure 9-6 Formatting Numbers

Using Conditional Formatting

Conditional formatting occurs when a formatting element appears only when a certain condition is met.

BI Publisher supports the usage of simple "if" statements, as well as more complex "choose" expressions.

For additional information, see Using Conditional Formatting .

Note:

To define a conditional block you can also use the conditional region wizard launched from the BI Publisher toolbar.

Using IF Statements

Use an if statement to define a simple condition; for example, if a data field is a specific value.

To use an if statement:

1. Insert the following syntax to designate the beginning of the conditional area. <?if:condition?>

2. Insert the following syntax at the end of the conditional area: <?end if?>

   <?if: [ELEMENT][CONDITION]?>

   Conditional block

   <?end if?>

Note:

Ensure the [ELEMENT] from the XML is referenced in matching case

Figure 9-7 Placeholders defining conditional block between <?IF()> and <?end if?>

IF statements can be combined with other string functions.

CONTAINS

Using the CONTAINS function, an expression can be constructed to output conditional text when an element contains a specific string value. This is similar to a LIKE operator.

<?if: contains(ELEMENT,’txt_to_search_for’)=’true’?>Yes it does <?end if?>

STARTS-WITH

To evaluate the start of a string, use the STARTS-WITH function:

<?if: starts-with(COMPANY_NAME,'Oracle')?><?end if?>

Using Inline IF Statements

You can use “if” statements to change text output in boilerplate text.

Use the BI Publisher context command to place the if statement into the inline sequence rather than into the block (the default placement).

Using the @inline syntax, a sentence string can be constructed conditionally; for example:

The program was <?if@inline:SUCCESS=’N’?>not<?end if?> successful.

Result in the output:

• The program was successful. (If SUCCESS does not equal ’N’)
• The program was not successful. (If SUCCESS equals ’N’)

For more information refer Controlling the Placement of Instructions Using the Context Commands.

Using IF-THEN-ELSE

BI Publisher supports the common programming construct "if-then-else". "if-then-else" is extremely useful when you must test a condition and conditionally show a result.

Use the following syntax to construct an if-then-else statement in the RTF template:

<?xdofx:if element_condition then result1 else result2 end if?>

For example, the following statement tests the AMOUNT element value. If the value is greater than 1000, show the word "Higher"; if it is less than 1000, show the word "Lower"; if it is equal to 1000, show "Equal":

<?xdofx:if AMOUNT > 1000 then 'Higher'
  else
  if AMOUNT < 1000 then 'Lower'
   else
   'Equal'
end if?>

Using CHOOSE Statement

Use the choose, when, and otherwise elements to express multiple conditional tests. If certain conditions are met in the incoming XML data, then specific sections of the template are rendered. This is a very powerful feature of the RTF template.

Use the following syntax for these elements:

<?choose:?>
<?when:expression?> <?end when?>
<?otherwise?> <?end otherwise?>  
<?end choose?>

  

For example, to output a string based on the VIP field:

 <?choose:?>
<?when:VIP_CODE='V1'?>You're a VIP1<?end when?>
<?when:VIP_CODE='V2'?>You're a VIP2<?end when?>
<?when:VIP_CODE='V3'?>You're a VIP3<?end when?>
 <?otherwise:?>You're not a VIP<?end otherwise?>
 <?end choose?>

Using the form field method; add the expression to the Help Text.

Figure 9-8 <?CHOOSE:?> Example

Adding Conditions for Internal Parameters

Each customizable report contains internal parameters that are used for report generation. These parameters can be utilized when creating conditions for report generation.

For example, if you need to display a graphic on a confirmation letter only when generating in PDF format, these internal parameters would be used.

The XML tags <PARAM_NAME>DESFORMAT</PARAM_NAME> and <PARAM_VALUE>PDF</PARAM_VALUE> are available .

In this example, a condition is created for text to only appear if the report output is PDF format. To accomplish this, add the field PARAM_NAME and then double click to edit. In the Form Field Help Text screen, insert the following line:

<?if:PARAM_VALUE[../PARAM_NAME='DESFORMAT']='PDF'?>

Insert an  <?end if?> statement after the image to close the conditional block

Figure 9-9 Conditional Image for PDF Output

Adding Hyperlinks for PDF and HTML Output

The RTF template may contain links on text and images to web locations.

When a hyperlink is setup on an image placeholder, the image becomes a click-able image (button) in the document.

When generated in PDF or HTML format, the PDF file / HTML email will contain those hyperlinks to launch the website.

1. Select the area of text or image in the template

2. Right click and select Hyperlink.

3. Enter the URL in the Address.

4. Click OK.

   Figure 9-10 Insert Hyperlink

   
   
   

5. Links can also be defined on images in the template for PDF and HTML output. Select an image and select Insert and then select Hyperlink. In the resulting email or PDF file, the image is a button the recipient can click to launch the URL.

Non-Western Fonts

Only OS-packaged, standard fonts are supported. To support internationalization and non-Western character sets, a Unicode font must be used in the RTF template. Arial Unicode and Lucinda Sans Unicode are two standard Unicode fonts installed with Microsoft Windows and Microsoft Office. Format any string or date field that outputs non-Western characters with Arial or Lucinda Sans Unicode to ensure correct output.

Note:

Alternate name XML elements (prefixed with X) will contain the western/primary name when no alternate name details exist for the profile. Your template layouts only need to reference the X-fields.

Figure 9-11 Selecting a Unicode font

Extended SQL and XSL Functions

BI Publisher has extended a set of SQL and XSL functions for use in RTF templates. The syntax for these extended functions are the following:

<?xdofx:expression?> for extended SQL functions 

<?xdoxslt:expression?> for extended XSL functions

An SQL example is IF-THEN-ELSE used for a conditional region.

<?xdofx:if [ELEMENT][condition] then result1 else result2 end if?>

Another for xdofx statements is to perform mathematical calculations; for example the expression

<?xdofx:nvl(TOTAL_COST_OF_STAY,0)-nvl(TOTAL_DEPOSIT_PAID,0)?> 

would subtract the value in the total_deposit_paid element from the value in the total_cost_of_stay element for a calculated field of the balance due. Enclosing each element with the NVL() function ensures 0 is returned when the element is NULL (has no value set).

For further information, refer to Extended SQL and XSL Functions.

Preview using Sample XML

Once you've finished customizing the template, you can preview from within Microsoft Word to verify the layout, format masks and test that conditions are correct.

From the BI Publisher tab on the toolbar, select Preview then select PDF or HTML

A file will generated using the data available in the sample XLM loaded for the template.

Figure 9-12 Preview Template

Save RTF File

Ensure you save your modified RTF template; from within Microsoft Word click Cntrl + S or click File then click Save.

Refer to step 11 in  Configuring Stationery Templates topic for information on uploading the modified RTF template to OPERA Cloud.