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

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

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.

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.

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

1. Enable the Forms toolbar in Microsoft Word.

2. Position the cursor in the location where you want to insert the QR code.

3. Select the Text Form Field toolbar icon. This action inserts a form field area in the template.

4. Double-click the form field area to invoke the Text Form Field Options dialog box.

5. (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

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.

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.

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

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 .

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: [ELEMENT][CONDITION]?>.

   Note:

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

2. Add the conditional text / image(s).

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

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.

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

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

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

 <?end if?>

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.