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.

Click the BI Publisher tab on the toolbar and click Sample XML.
Navigate to the folder where the sample XML file was downloaded to.
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

This figure shows the BI Publisher Template Builder for Word menu option.

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

Adding QR Codes

Enable the Forms toolbar in Microsoft Word.
Position the cursor in the location where you want to insert the QR code.
Select the Text Form Field toolbar icon. This action inserts a form field area in the template.
Double-click the form field area to invoke the Text Form Field Options dialog box.
(Optional) Enter a description of the field in the Default text field. The entry in this field populates the placeholder's position on the template.
1. Select the Add Help Text button.
2. In the help text entry field, enter the expression : <fo:instream-foreign-object content-type="image/jpg"> <xsl:value-of select=".//<QRCODE>"/> </fo:instream-foreign-object>, replacing <QRCODE> with the code setup in QR Code Definition.
3. Click OK to apply.

Inserting Images

There are two methods for inserting images into templates:

Embedding images in the RTF template
Referencing images available on a website or content management system.

Embedding images quickly increases the template's size, whereas referencing external images results in a significantly smaller file. Externally referenced images can also be updated without modifying the template(s).

For HTML confirmation email delivery, the image URL reference method must be used. The recipient's email client will download the images from the website or content management system when the email is opened and display the image at the specified location in the email body.

Note:

By default, emails client may block images from initial download and provide a specific action to download these images on demand.

Reference Image by URL

Referencing web images results in the image is fetched at runtime from a cloud server or content management system. This method of adding images to templates is suitable for both PDF or HTML email delivery. An email client will download the image from the server as needed.

To add images by URL references:

Insert a dummy image by selecting Insert and then selecting Pictures. The dummy image can be set to the required size using Word's picture tools.
Insert a dummy graphic into the layout in Word by selecting Insert and then selecting Pictures.
Right-click the image and select the Format Picture option and then click the Alt Text tab.
1. Enter the following syntax to reference the image location:
  
  url:{'https://<image location>'}.
  
  For example, enter: url:{'https://www.example.com/images/oracle_logo.gif'}

An image URL is used to generate the property logo. Each sample template contains a placeholder image with

url:{concat($IMAGES_PATH,'/',/DATA/LIST_REPORT/REPORT/LOGO_IMAGE,'.',$IMAGES_TYPE)or

url:{concat($IMAGES_PATH,'/',/DOCUMENT/BOOKING/BOOKING_ROW/PROPERTY,'.',$IMAGES_TYPE) to generate a dynamic URL for the property logo.

At runtime, the placeholder image is replaced with the image available at the specified web address (URL).

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:

Double click the date placeholder in the template.
Set Text to Display to a test date.
Set Type to Date.
Select a date format from the list.
Click OK.

Figure 9-4 Formatting Dates

Formatting Numbers

To apply a MS Word format mask to number fields:

Double click the number placeholder in the template.
Set Text to Display to a test number.
Set Type to Number.
Select a number format from the list.
Click OK.

Figure 9-5 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:

Insert the following syntax to designate the beginning of the conditional area <?if: [ELEMENT][CONDITION]?>.

Note:
Ensure the [ELEMENT] from the XML is referenced in matching case.
Add the conditional text / image(s).
Insert the following syntax at the end of the conditional area <?end if?>.

Figure 9-6 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-7 <?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 and are available.

The XML tags

<PARAM_NAME>DESFORMAT</PARAM_NAME>

<PARAM_VALUE>PDF</PARAM_VALUE>

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

Select the area of text or image in the template.
Right click and select Hyperlink.
Enter the URL in the Address.
Click OK.

Figure 9-9 Insert Hyperlink
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.

Asian Character Sets

Use DengXian font for Chinese or Japanese characters. For other characters use a Unicode font in the template; all text formatted with a Unicode font is generated using the Arial Unicode font.

Note:

Bold, italic and underline styling is not supported by the Arial Unicode font.

Alternate name data elements are prefixed with 'X' (example: XLAST_NAME) in the sample data model. At runtime, if no alternate name exists, these 'X' data elements contain the western (primary) name. Therefore, your templates only need to reference the x-fields and dynamically output the alternate or primary name. Format these fields in a suitable font for the language of the template.

Figure 9-10 Alternate Name

Alternate name XML elements (prefixed with X)

Using Barcode Fonts

The following table describes the barcodes that are included with BI Publisher.

Font File	Supported Algorithm
128R00.TTF	code128a, code128b, and code128c
B39R00.TTF	code39, code39mod43
UPCR00.TTF	upca, upce
MICR____.TTF	E-13B

When you use one of these prepackaged fonts, BI Publisher executes the preprocessing on the data prior to applying the barcode font to the data in the output document. For example, to calculate checksum values or start and end bits for the data before formatting them.

To use the barcode fonts in the report output:

Insert a field in the template where the barcode is to display in the report output.
In the form field, enter the following command:
```
<?format-barcode:data;'barcode_type'?>
```
where:
- data is the element from the XML data source to be encoded. For example: INVOICE_NO
- barcode_type is one of the supported algorithms listed above.
Examples:
```
<?format-barcode:INVOICE_NO;'code128a'?>  

<?format-barcode:INVOICE_NO;'code39mod43'?>  

<?format-barcode:INVOICE_NO;'upca'?>
```
In Microsoft Word, apply the barcode font to the field.

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 defining a conditional region or defining conditional output.

<?xdofx: if RESERVATION_STATUS='CANCELLED' then 'Cancellation Number:' else 'Confirmation Number:' end if?> <?xdofx: if RESERVATION_STATUS='CANCELLED' then CANCELLATION_NO else CONFIRMATION_NO end if?>

These two expressions would result in either:

Cancellation Number: 123456
Confirmation Number: 987654

Calculating Dates

You can calculate dates using the ora_format_date_offset() function and referencing Canonical date fields from the XML.

The expression <?xdoxslt:ora_format_date_offset(DATE_IN_ISO,X,'+')?> adds X number of days to the date_in_iso field.

The expression <?xdoxslt:ora_format_date_offset(DATE_IN_ISO,Y,'-')?> subtracts Y number of days from the date_in_iso field.

For example to add 14 days to the arrival_date_iso field:

<?xdoxslt:ora_format_date_offset(ARRIVAL_DATE_ISO,14,'+')?>

The calculated date form field can be formatted using Word native date formatting.

Alternatively, you can use the Oracle <?format-date?> function to format a calculated date.

For example to format a calculated date with 'DD-MM-YYYY' mask :

<?format-date:xdoxslt:ora_format_date_offset(ARRIVAL_DATE_ISO,14,'+');'DD-MM-YYYY'?>

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