Skip Headers
Oracle® Fusion Middleware Report Designer's Guide for Oracle Business Intelligence Publisher
11g Release 1 (11.1.1)

Part Number E22254-03
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

5 Creating RTF Templates Using the Template Builder for Word

This chapter describes creating RTF templates in BI Publisher using the Template Builder for Word add-in.

This chapter includes the following sections:

5.1 Overview

The Template Builder is an add-in to Microsoft Word that simplifies the development of RTF templates. While the Template Builder is not required to create RTF templates, it provides many functions that increase productivity.

The Template Builder is tightly integrated with Microsoft Word and enables you to perform the following functions:

The Template Builder automates insertion of the most frequently used components of an RTF template. RTF templates also support much more complex formatting and processing. For the full description of RTF template features, see Chapter 4, "Creating RTF Templates."

5.1.1 Before You Get Started

The Template Builder installation provides samples and demo files to help you get started. The demos can be accessed from the Windows Start menu as follows:

Select Start, Programs, Oracle BI Publisher Desktop, and Demos.

You can also access the demos from the BI Publisher\BI Publisher Desktop\demos folder where you installed BI Publisher Desktop (for example: C:\Program Files\Oracle\BI Publisher\BI Publisher Desktop\demos).

The following demos are provided:

  • TemplateBuilderDemo.exe - Demonstrates building a report layout using many key features of the Template Builder, including: connecting to the BI Publisher server, loading data for a report, inserting tables and charts, and defining conditional formatting.

  • TemplateBuilderInvoice.exe - Demonstrates how to take a prepared layout and use the Template Builder to insert the required fields to fill the template with data at runtime.

  • LocalizationDemo.exe - Demonstrates the localization capabilities of the Template Builder and shows you how to extract an XLIFF file from the base RTF template. The XLIFF file can then be translated and the translations previewed in the Template Builder.

The sample files are located in the BI Publisher\BI Publisher Desktop\Samples folder. The Samples folder contains the subfolders:

  • eText templates

  • Excel templates

  • PDF templates

  • RTF templates

The eText, PDF, and Excel template samples can be used as references to create these types of templates. The Template Builder is only available for the RTF templates. The RTF templates folder contains eight subfolders to provide samples of different types of reports. Refer to the TrainingGuide.html located in the RTF templates folder for additional information on what is contained in each sample.

5.1.2 Prerequisites and Limitations

The following list describes prerequisites and limitation for this feature:

  • Prerequisites:

  • Limitations:

    • The Template Builder does not support bidirectional display of text in the user interface.

5.2 Getting Started

This section describes how to get started. It contains the following topics:

5.2.1 Features of the Oracle BI Publisher Template Builder for Word

When you open Microsoft Word after installing the Template Builder, you see the Oracle BI Publisher menu.

For versions of Microsoft Word prior to 2007, the menu and toolbar are displayed as shown in Figure 5-1.

Figure 5-1 Display of the Menu and Toolbar in Versions of Microsoft Word Prior to 2007

Description of Figure 5-1 follows
Description of "Figure 5-1 Display of the Menu and Toolbar in Versions of Microsoft Word Prior to 2007"

For Microsoft Word 2007 users, the BI Publisher commands are displayed in the ribbon format, as shown in Figure 5-2.

Figure 5-2 BI Publisher Commands Displayed in the Ribbon Format

Description of Figure 5-2 follows
Description of "Figure 5-2 BI Publisher Commands Displayed in the Ribbon Format"

Use the menu (or toolbar) to perform the following:

  • Insert data fields into age RTF templates

  • Insert tables, forms, charts, and pivot tables

  • Preview the template in multiple outputs

  • Browse and update the content of form fields

  • Validate the template

  • Perform calculations on fields within the template

  • Connect to the Oracle BI Publisher catalog to retrieve data to build the template

  • Upload the template to the Oracle BI Publisher server

  • Extract boilerplate text into an XLIFF translation file and test translations

5.2.2 Building and Uploading a Template

You can build and upload the template using a direct connection with the BI Publisher server, or you can build and upload the template in disconnected mode.

5.2.2.1 Working in Connected Mode

To work in connected mode:

  1. Open Microsoft Word.

  2. From the Oracle BI Publisher menu, select Log On.

  3. Enter your BI Publisher credentials and the URL for the BI Publisher server, for example: http://www.example.com:7001/xmlpserver. (Contact your system administrator if you do not know the URL.)

  4. The Open Template dialog presents the same folder structure as the BI Publisher catalog. Select the report or data model for which you want to build a template.

  5. If you selected a data model:

    Click Create Report to create a report for this data model in the BI Publisher catalog. This is the report that you upload the template to.

    Enter a Report Name and select the folder in which to save it.

    Click Save.

    The sample data from the data model is loaded to the Template Builder.

    If you selected a report:

    Click Open Report to load the data to the Template Builder; or double-click <New> in the Layout Templates pane, as shown in Figure 5-3.

    Any existing templates are listed in the Layout Templates pane.

    Figure 5-3 The Layout Templates Pane

    Description of Figure 5-3 follows
    Description of "Figure 5-3 The Layout Templates Pane"

  6. Follow the guidelines in this chapter to insert data fields and design the template using features such as tables, charts, and graphics. Use Microsoft Word to apply formatting to fonts and other objects in the template.

    For more advanced template options, use the guidelines in Chapter 4, "Creating RTF Templates."

  7. To upload the template file to the BI Publisher server and add it to the report definition, select Upload Template As from the Oracle BI Publisher menu.

    If you have not saved the template, then you are prompted to save it in Rich Text Format.

  8. Enter a name and select a locale in the Upload as New dialog. This is the name that is displayed under Layouts in the Report Editor. This is also the layout name that is displayed when a user runs this report.

  9. Configure properties for this layout.

    Navigate to the BI Publisher report editor to configure properties for this layout, such as output formats. See Section 2.7.3, "Configuring the Layout Settings Using the List View" for more information.

5.2.2.2 Working in Disconnected Mode

To work in disconnected mode, you must have a sample data file available in the local work environment.

To work in disconnected mode:

  1. Save a sample data file to your local computer. See Section 5.3, "Accessing Data for Building Templates."

  2. Open Microsoft Word with the Template Builder installed.

  3. On the Oracle BI Publisher menu in the Load Data group select Sample XML. Locate the sample data file in the local directory and click Open.

    Note:

    The Template Builder also supports using XML Schema to design an RTF template. However, because the schema contains no data, the preview of the report also contains no data.

  4. Follow the guidelines in this chapter to insert data fields and design the template using features such as tables, charts, graphics, and other layout components. Use Microsoft Word to apply formatting to fonts and other objects in the template.

    For more advanced template options, use the guidelines in Chapter 4, "Creating RTF Templates."

  5. Upload the layout template file.

    In the BI Publisher catalog, open the report in the Report Editor. Click Add New Layout.

    Complete the fields in the dialog and then select Upload. The template now appears as a layout for the report.

  6. Configure properties for this layout.

    See Section 2.7, "Configuring Layouts Using the List View" for more information.

5.3 Accessing Data for Building Templates

The data model defines the XML format that is merged with the RTF template. The Template Builder requires sample data to build the template. You must load sample data to use most of the template builder functionality.

If you are not connected to BI Publisher, then use the procedure in Section 5.3.1, "Loading XML Data from a Local File." If you are connected, then use the procedure in Section 5.3.2, "Loading Data from the BI Publisher Catalog."

5.3.1 Loading XML Data from a Local File

One method of loading data to the Template Builder is to save a sample of the report data to a local directory.

For information on saving sample data from a report data model, see the "Testing Data Models and Generating Sample Data" section in Oracle Fusion Middleware Data Modeling Guide for Oracle Business Intelligence Publisher.

If you do not have access to the report data model, but you can access the report, then you can alternatively save sample data from the report viewer.

To save data from the report viewer:

  1. In the BI Publisher catalog, navigate to the report.

  2. Click Open to run the report in the report viewer.

  3. Click the Actions icon, then click Export, then click Data. You are prompted to save the XML file.

  4. Save the file to a local directory.

  5. Use the Load Sample XML feature below to load the saved XML file to the Template Builder.

The Load Data group from the Oracle BI Publisher menu enables you to select and load the saved XML file to the Template Builder.

  • Sample XML - Enables you to load a sample XML file that contains all fields that you want to insert into the template as a data source. If you are not connected to the BI Publisher server, then use this method to load the data.

  • XML Schema - Enables you to load an XML Schema file (.xsd) that contains the fields available in the report XML data. The XML schema has the advantage of being complete (a sample XML file might not contain all the fields from the data source). For the preview, the Template Builder can generate dummy sample data for an XML Schema. However, the preview works better if you also upload real sample data.

5.3.2 Loading Data from the BI Publisher Catalog

You can connect directly to the BI Publisher Server to load the BI Publisher report data to the Template Builder to use as sample data for designing layouts. You can also download an existing template to modify it.

To connect to BI Publisher and load a data source:

  1. Log on to the BI Publisher Server: From the Oracle BI Publisher menu, select Log On. For more information on logging in to the BI Publisher server, see Section 5.2.2.1, "Working in Connected Mode."

  2. After you area logged on, you can select Open. The Open Template dialog launches.

  3. Navigate to the folder that contains the report or data model for which you want to create a template.

    When you select a report, you can either select from the Layout Templates to open an existing template, select Open Report to load just the XML sample data to create a new layout, or double-click <New> to load the data to the Template Builder to build a new layout.

    When you select a data model, you are prompted to create a report in the catalog.

5.4 Inserting Components to the Template

This section includes the following topics:

5.4.1 Inserting a Field

This dialog enables you to select data elements from the data source and insert them into the template.

In the Insert group select Field to open the Field dialog. The dialog shows the structure of the loaded data source in a tree view, as shown in Figure 5-4.

Figure 5-4 The Field Dialog

Description of Figure 5-4 follows
Description of "Figure 5-4 The Field Dialog"

Select a field that represents a single data field (a leaf node of the tree) and select Insert (you can also insert the field by dragging and dropping it into the document, or by double-clicking the field). A text form field with hidden BI Publisher commands is inserted at the cursor position in the template. You may either select and insert additional data fields or close the dialog by clicking the Close button.

5.4.1.1 About the Insert Field Dialog

The Insert Field dialog fields are described in the following sections:

5.4.1.2 Find

For an XML document with a large and complicated structure, use the find functionality to find a specific field. Enter a partial string of the field name you are searching into the Find field and click Find Next. The next occurrence of a data element that includes the search expression is selected. Click the Find Next button again to see the next occurrence.

5.4.1.3 Example

When you select a field name in the tree view, an example value for this field is shown.

5.4.1.4 Force LTR (Left-to-Right) Direction

This check box is only needed if you are using the template in a language that prints the characters from right to left, such as Arabic or Hebrew. Use this feature to force left-to-right printing for fields such as phone numbers, addresses, postal codes, or bank account numbers.

5.4.1.5 Calculation

This feature enables you to perform aggregation functions on data fields, such as sum, average, count, minimum, and maximum.

For example, if you select sum for a data field, then the field shows the sum of all occurring values for this data field, depending on the grouping.

It is important to understand the grouping context (marked by G and E form fields) to know exactly which fields are accumulated. If you insert a data field with an accumulation function into a repeating section (marked by G and E processing instruction form fields), you must select On Grouping to accumulate the data for the occurrences within the group. If you do not want the accumulation to be restricted to the group, you must place the accumulation field outside the group.

Figure 5-5 shows an example.

Figure 5-5 Grouping Context Example

Description of Figure 5-5 follows
Description of "Figure 5-5 Grouping Context Example"

Also note that the data field must be a valid XSL number for the accumulation functions to work. Formatted numbers cannot be processed by BI Publisher (for example a number using a thousands separator: 10,000,000.00 cannot be processed).

For more information on groups in s template using the Template Builder, see Section 5.4.5, "Inserting a Repeating Group" and Section 4.4, "Defining Groups."

5.4.2 Inserting a Table Using the Table Wizard

The Insert Table Wizard enables you to create standard reports. On the Insert menu select Table Wizard and complete the following steps:

5.4.2.1 Step 1: Select Report Format

Start by selecting the basic report format. Choose from Table, Form, or Free Form. Figure 5-6 shows examples of each format.

Figure 5-6 Examples of Table, Form, and Free Form Formats

Description of Figure 5-6 follows
Description of "Figure 5-6 Examples of Table, Form, and Free Form Formats"

5.4.2.2 Step 2: Select Table Data

An XML document can include multiple grouped data sets. For example, a purchase order XML document may contain header level information, lines, shipments and contacts.

In this step, select the data group that contains the data that is required for the table.

For example, in the Balance Letter sample RTF template (found in the Template Builder installed files under Oracle\BI Publisher\BI Publisher Desktop\samples\RTF Templates), the sample XML file contains three data groups as follows:

  • ARXCOBLX/G_CUSTOMER

  • ARXCOBLX/G_CUSTOMER/G_CURRENCY

  • ARXCOBLX/G_CUSTOMER/G_CURRENCY/G_INVOICES

The Table Wizard presents a list of the available data groups in the XML data file. Select the group that contains the data fields for the table.

Figure 5-7 shows the Table Wizard Step 2: Selecting Table Data.

Figure 5-7 The Table Wizard Step 2: Selecting Table Data

Description of Figure 5-7 follows
Description of "Figure 5-7 The Table Wizard Step 2: Selecting Table Data"

To build a table to list the invoices contained in the data, select:

ARXCOBLX/G_CUSTOMER/G_CURRENCY/G_INVOICES

as the data set.

5.4.2.3 Step 3: Select Data Fields

The Table Wizard presents the data fields from the selected data set.

Figure 5-8 shows the Table Wizard Step 3: Selecting Data Fields.

Figure 5-8 The Table Wizard Step 3: Selecting Data Fields

Description of Figure 5-8 follows
Description of "Figure 5-8 The Table Wizard Step 3: Selecting Data Fields"

Use the shuttle buttons to select the data fields to show in the table. Use the up and down arrows to reorder the fields after selecting them.

5.4.2.4 Step 4: Group the Table

This step enables you to regroup the data by a particular field. This is optional.

For example, if you are building a table of invoices, you may want to group all invoices of a particular type or date to be grouped together in the report.

Figure 5-9 shows the Table Wizard Step 4: Grouping the Table.

Figure 5-9 The Table Wizard Step 4: Grouping the Table

Description of Figure 5-9 follows
Description of "Figure 5-9 The Table Wizard Step 4: Grouping the Table"

There are two options for grouping: Group Left or Group Above. Group Left creates a nested table. The Group By field displays to the left in the outer table. Group Above creates a new table for each new value of the group by field, displaying the value of the group by field as a table title.

Examples follow:

Group Left groups the group by element occurrences together, as shown in Figure 5-10.

Figure 5-10 Results of the Group Left Option

Description of Figure 5-10 follows
Description of "Figure 5-10 Results of the Group Left Option"

Group Above shows the result as a table with a header, as shown in Figure 5-11.

Figure 5-11 Results of the Group Above Option

Surrounding text describes Figure 5-11 .
Description of Figure 5-11 follows
Description of "Figure 5-11 Results of the Group Above Option"

When you select an element to group by, BI Publisher sorts the data by the grouping element. If the data is already sorted by the grouping element, then select the Data already sorted check box. This selection improves performance.

5.4.2.5 Step 5: Insert a Break for the Group

Use the Break option to insert either a Page break or Section break after each occurrence of this group. Note that a Section break can only be created on the top-level group. The subsequent grouping options only display the Page break option.

A page break starts the next group on a new page; a section break starts the next group on a new page, reset page numbering, reset headers and footers, and reset any running calculations for each occurrence of the group.

5.4.2.6 Step 6: Sort the Table

You can sort the data in the table by up to four different fields. Select a field and then define the sorting order (ascending or descending), and select the correct data type for the field. For example, if text is selected, "12" comes before "2" (alphanumerical order). If number is selected, "2" comes before "12".

Figure 5-12 shows the Table Wizard Step 6: Sorting the Table.

Figure 5-12 The Table Wizard Step 6: Sorting the Table

Description of Figure 5-12 follows
Description of "Figure 5-12 The Table Wizard Step 6: Sorting the Table"

5.4.2.7 Step 7: Click Finish

Click Finish to create the table and insert it to the Microsoft Word document.

5.4.2.8 Step 8: Customize the Table Using Microsoft Word Functionality

Customize the table by changing fonts, colors, column sizing, borders, shading, and so on, using Microsoft Word formatting commands.

5.4.3 Inserting a Table or Form Using the Insert Table/Form Dialog

The Insert Table/Form dialog is the most flexible tool of the template builder. It allows you to perform the following tasks:

  • Create a simple or nested table with a variable number of rows.

  • Associate a group of data elements, such as a complete invoice or a purchase order line, with a form in the document that is repeated for each occurrence of the data element.

  • Select and define a layout for all the data fields in the template.

  • Group or re-group the data.

The Insert Table/Form dialog shows you two tree view panes. The left pane shows the data source structure, while the right pane shows the elements that are copied to the template when you click the Insert button.

5.4.3.1 Selecting Data Fields

First select the data fields to insert in the template and then define how to format them. Drag an XML element from the left Data Source pane to the right Template pane. If the XML element has children, you see a pop-up menu with the following options:

  • Drop Single Node

  • Drop All Nodes

  • Cancel

Select Drop Single Node if you want to move only the selected node or Drop All Nodes if you want to move the node and all its children.

If you drag an additional data field from the left Data Source pane to the right Template pane, it is either inserted at the same level (Same Level) or below the node (Child) where you release the node. The Insert Position box defines where the node is inserted.

Note:

If you use the left mouse button for drag and drop, then the node and all children are copied. However, if you use the right mouse button for dragging, a dialog is displayed when you release the mouse button. The dialog gives you the option to copy either only the selected node or the selected node and all children.

5.4.3.2 Defining the Layout

When you select an element in the right Template pane, you see its properties as well as a preview of how the node is rendered. There are two kinds of nodes:

  • Data Fields

  • Data Groups

Data Field nodes (leaf nodes) do not have any child nodes. They represent simple attributes such as the total amount for an invoice or the subtotal for a purchase order line.

Data Group nodes (parent nodes) are nodes that do have child nodes. Typically, they do not represent data attributes, but groups of data - such as an invoice, a purchase order, a purchase order line or a shipment.

5.4.3.3 Data Field Properties

If a Data Field node is selected, its properties are shown in the Properties pane. You have the following options to describe how the Template Builder should show the field:

  • Calculation

    You can select one of the aggregation functions for the data fields. These functions (besides count) only have an effect when there is more than one of the data fields in the context where you use the function.

  • Force LTR (Left-to-Right) Direction

    This option is only needed if you are using the template in a language that displays characters from right to left, such as Arabic or Hebrew. Use this option to force left-to-right printing for fields such as phone numbers, addresses, postal codes, or bank account numbers.

5.4.3.4 Data Group Properties

The order in which the data elements are shown reflects the order of the columns in the table. If you want to reorder the columns, change the Insert Position box from Child to Same Level. Then drag the elements into the correct order.

If a Data Group node is selected, its properties are shown in the Properties pane. You have the following options to describe how the Template Builder should render the group:

  • Style

    To display the data as a horizontal table with a header, select Table. To display the fields below each other with labels in a table, use Form. If you want to insert the fields into a free-form text section that should to repeated for this element select Free Form.

  • Grouping

    Grouping is an advanced operation that allows you to group the data by a specific element in the data. For example, you might want to group all invoices by customer. You can select a child element of the selected element as a grouping criterion. For more information see Section 5.4.3.6, "Grouping."

  • Show Grouping Value

    This property is shown only if you have selected a node created by the Grouping functionality. By default, the field you have selected to group the data by is displayed in the report. If you do not want the grouping data field displayed, then select No.

  • Sort By

    Select an element by which the data groups are sorted.

  • Sort Order

    If you have selected an element for Sort By you can select if the data should be sorted either ascending or descending.

  • Sort Data Type

    If you have selected an element for Sort By the data is by default sorted as text. That means that 12 is shown after 111. If the data is numeric, select Number as the sort data type.

  • Break

    This property allows you to insert a page break or a section break between every data group. If you select New Page per Element, then a page break is inserted between each element after the first occurrence.

    Tip:

    To insert a page break before the first occurrence of an element, use Microsoft Word's page break command.

    If you select New Section per Element, then a section break is created for each data group. A section break has the following effects: it inserts page break, it resets the page numbers and new data can be displayed in the header and footer. You typically use this option if you want to print multiple documents (for example invoices or purchase orders) to a single PDF file.

5.4.3.5 Inserting Tables and Forms

Once you have dragged all data fields over and defined the layout, select the Insert button to place the tables and forms at the cursor position in the document.

5.4.3.6 Grouping

You can group any Data Group node, by any of its child Data Field Nodes. For example if you have sales data for multiple quarters, you may want to show the sales data organized by quarter. In this case you would group the sales data rows by the quarter element.

Assume the following structure:

Sales Transaction
       Quarter
       Customer
       Amount

To group the child nodes of a node (Sales Transaction), you select one of the child nodes (Quarter) as the grouping property of the parent node (Sales Transaction). The Template Builder makes this node (e.g. quarter) the parent of the other child nodes (Customer and Amount).

The new structure looks like the following:

Sales Transaction
       Quarter
            Customer
            Amount

The grouping criterion (Quarter) now behaves like any other Data Group Node with children. That means that you can define the layout of its children using the Create As Table, Style, Label, Grouping, and Show Grouping Value properties.

5.4.3.7 Understanding Fields Inserted to the Template

The Insert Table/Form Dialog creates two kinds of form fields:

  • Form fields representing data elements

  • Form fields with processing instructions for repeating table rows or document sections

Form fields representing data elements are replaced with the data when the template is processed. Form fields indicating repeating sections are shown as for-each and end for-each in the document.

Note:

If you have selected the Abbreviated form field display option, then the for-each and end for-each form fields are displayed as F and E. The section of the document encapsulated by these two elements is repeated, if the associated data element is repeated in the data.

5.4.4 Inserting a Chart

Use the Chart dialog to insert a chart into a template.

Figure 5-13 shows the Chart dialog.

Figure 5-13 The Chart Dialog

Description of Figure 5-13 follows
Description of "Figure 5-13 The Chart Dialog"

5.4.4.1 Chart Type

BI Publisher supports a large variety of chart types. Expand the Type list to select the chart type for this template.

5.4.4.2 Values

Drag and drop the data value you want to measure to the Values field (for example, SALES). You can select multiple Value elements (measures).

The Values field changes depending on the Chart Type that you select:

  • Combination Graph - Enables three fields for the Value selections.

  • Scatter Graph  - Compares pairs of values. Drag and drop the X and Y data elements to compare.

  • Bubble Graph - Compares sets of three values. Similar to the scatter graph, the third value is displayed as the size of the bubble.

  • Stock Graph - Drag and drop the elements that represent the Open, High, Low, Close, and Volume values for the stock graph.

5.4.4.3 Aggregation

You can choose to aggregate the Values data as a sum, a count, or an average.

5.4.4.4 Labels

Drag and drop the data element for which you want to see the Value charted (for example, Year). Select Group Data to group the occurrences of the label element before rendering it in the chart. For example, if you are charting Sales by Year, then selecting Group Data accumulates the values for Year, so that only one occurrence of each year is displayed in the chart. If you do not select Group Data, then the value for every occurrence of Year in the data is plotted separately.

5.4.4.5 Color

If you want to add a series element to the chart, then drag and drop the element to display as a series. Each value is displayed as a new color in the graph.

5.4.4.6 Chart is Inside Group

Select this box if the chart is inside a grouping and you want the chart to display data only for the occurrences of the data elements within the group.

5.4.4.7 Style

Select a color scheme and style for the chart.

5.4.4.8 Properties

The properties region enables you to change value and label display names, select color, font, and other display options for the chart. The properties list changes depending on the chart selection.

5.4.4.9 Preview

Click Preview to display the chart with the sample data.

5.4.4.10 Group Data

By default the data is grouped by the Value element and aggregated by sum.

If you deselect the Group Data check box, the each occurrence of the value element is charted and aggregation functions are not available.

5.4.4.11 Editing an Inserted Chart

To edit a chart that you have already inserted into the template, right-click the chart and select BI Publisher Chart from the menu. This invokes the chart dialog to enable you to edit the chart.

5.4.5 Inserting a Repeating Group

To insert a repeating group:

  1. Select the section of the template that contains the elements you want repeated.

  2. On the Oracle BI Publisher menu, in the Insert group, click Repeating Group.

  3. Enter the appropriate fields in the BI Publisher Properties dialog, as shown in Figure 5-14.

    Figure 5-14 The BI Publisher Properties Dialog

    Description of Figure 5-14 follows
    Description of "Figure 5-14 The BI Publisher Properties Dialog"

    For Each

    Select the element that for each occurrence, you want the loop to repeat. When you select the For Each data field you are telling BI Publisher that for each occurrence of the selected field in the data you want the elements and processing instructions contained within the loop to be repeated.

    For example, assume that the data contains invoice data for customers and you want to create a table with each customer's invoices. In this case, for each customer number you want the table to repeat. You would therefore select the customer number in the For Each field to create a new loop (or group) for each customer.

    Note the following about creating repeating groups:

    • For loops and groupings not inside another group (that is, outer groups or loops) you must select the repeating XML element to be used. For example if the data set is flat, the only repeatable element is /DATA/ROWSET/ROW. In cases with multiple data sources or hierarchical XML you can choose the data set.

    • If you are creating nested groups (inserting a loop or group inside of another loop in the template), the For Each field is not updatable because it is already defined by the preexisting outer loop. The For Each field is displayed as "Group Item" to inform you that an outer group is already defined.

    Absolute Path

    Select this check box to use the Absolute Path to the element in the XML structure. This is important if the data contains the same element name grouped under different parent elements.

    Group By

    Select a field from the list by which you want to group the data. If you just want to create a simple loop, do not select a group by element. Selecting a group by element actually regroups the data into a new hierarchy based on the group by element.

    Break

    Use this option to create either a Page break or Section break if you want to insert a break after each occurrence of this group.

    A Section break can only be created on outer groups that surround the whole document. If the selected field is not an outer group, the Section break option is not available.

    Note also that when you insert a section break, the page numbering is reset, headers and footers are reset, and any running calculations are reset for each occurrence of the group.

  4. To sort the grouped data, select the Sorting tab. You can select up to four sort-by fields. For each sort by field, select the following:

    Sort order - Select Ascending or Descending.

    Data Type - Select Number or Date/Text. It is important that you select the correct data type to achieve the expected sort order.

    If you are sorting by four criteria and the XML data element names are long, then you might exceed the character length limitation (393 characters) of the Microsoft Word form field.

  5. The Advanced tab enables you to edit the code directly and to enter Text to Display for the field.

    The Code region displays the code and processing instructions that the Template Builder has inserted for the field. You can edit this if you want to change the processing instructions for this field.

    The Text to Display field shows how this field displays in the template. You can choose to enter descriptive text to enable you to understand each field better when reading the template, or you can enter abbreviated text entries that are less intrusive to the look and feel of the template.

    Note:

    You can set the default display text as Descriptive or Abbreviated using the Options tab.

    Figure 5-15 shows the Advanced tab of the BI Publisher Properties dialog.

    Figure 5-15 The BI Publisher Properties Dialog: Advanced Tab

    Description of Figure 5-15 follows
    Description of "Figure 5-15 The BI Publisher Properties Dialog: Advanced Tab"

  6. When you have completed the dialog options, click OK. This inserts the form fields in the template. By default, the beginning for-each form field displays the text "F" and is inserted at the beginning of the selected template section. At the end of the selection, an "E" form field is inserted to denote the end of the repeating group.

5.4.6 Creating Grouping Fields Around an Existing Block

To create a group around an existing block of text or elements in a template:

  1. Select the block of text. For example, a table row.

    If any preexisting BI Publisher tags are included in the block, then you must include the beginning and ending tags. For example, if the block contains any opening for-each, if, or for-each-group tags, then you must include the end for-each, end-if, and end for-each-group tags in the selection.

  2. On the Oracle BI Publisher menu, on the Insert group, click Repeating Group.

  3. In the BI Publisher Properties dialog, enter the fields to define the group as described in Section 5.4.5, "Inserting a Repeating Group."

  4. Click OK to insert the grouping fields around the block. For example, if the block is a table row, then the begin field is inserted at the beginning of the first cell and the end field is inserted at the end of the last field.

5.4.7 Inserting a Pivot Table

To insert a pivot table:

  1. On the BI Publisher menu on the Insert group, click Pivot Table. The Pivot Table dialog presents the data in the left pane with empty Layout panes on the right for you to drag and drop data elements. Figure 5-16 shows the Pivot Table dialog.

    Figure 5-16 The Pivot Table Dialog

    Description of Figure 5-16 follows
    Description of "Figure 5-16 The Pivot Table Dialog"

  2. Drag and drop the elements from the Data pane to the Layout pane to build the pivot table structure. In Figure 5-17, the layout shows Sales by Industry accumulated by Year and by Month.

    Figure 5-17 A Layout Showing Sales by Industry Accumulated by Year and by Month

    Description of Figure 5-17 follows
    Description of "Figure 5-17 A Layout Showing Sales by Industry Accumulated by Year and by Month"

  3. Use the Properties pane to select Aggregation. You can choose Sum, Count, or Average. Then choose a number Format, as shown in Figure 5-18.

    Figure 5-18 The Format Option

    Description of Figure 5-18 follows
    Description of "Figure 5-18 The Format Option"

  4. By default subtotals for rows and columns are displayed. You can choose not to display the subtotals by setting the properties to False.

    Figure 5-19 shows the properties for setting totals and subtotals.

    Figure 5-19 Properties for Setting Totals and Subtotals

    Description of Figure 5-19 follows
    Description of "Figure 5-19 Properties for Setting Totals and Subtotals"

  5. Click Preview to see how the pivot table is displayed before you insert it into the template. Click OK to insert the pivot table into the template. Figure 5-20 shows how the pivot table is displayed in the template.

    Figure 5-20 Example of a Pivot Table in a Template

    Description of Figure 5-20 follows
    Description of "Figure 5-20 Example of a Pivot Table in a Template"

    At runtime, this pivot table is generated as shown in Figure 5-21.

    Figure 5-21 A Pivot Table at Runtime

    Description of Figure 5-21 follows
    Description of "Figure 5-21 A Pivot Table at Runtime"

5.4.8 Manually Editing a Pivot Table

This section describes the code inserted by the pivot table builder. When the Template Builder inserts the pivot table, it inserts a BI Publisher command of the following structure:

<?crosstab: ctvarname; "data-element"; "rows"; "columns"; "measures"; "aggregation"?>

Table 5-1 Pivot Table Command Parameters

Parameter Description Example

Ctvarname

Crosstab variable name. This is automatically generated by the Add-in.

C123

data-element

This is the XML data element that contains the data elements to include in the pivot table. If the pivot table is inside a repeating group, this field must be manually edited to achieve the expected results. See the table following this section.

"//ROW"

rows

This parameter defines the XML elements for row headers. The ordering information is specified within "{" and "}". The first attribute is the sort element.If not specified, the row header element is used as the sort element.

Supported attributes are:

  • o - specifies the sort order. Valid values are "a" for ascending or "d" for descending.

  • t - specifies the data type. Valid values are "t" for text or "n" for numeric.

You can specify more than one sort element, for example:

"emp-full-name {emp-lastname,o=a,t=n}{emp-firstname,o=a,t=n}"

sorts employee by last name and first name. Note that the sort element can be any element in the data set, and does not have to be included in the pivot table. In the preceding example, emp-lastname and emp-firstname do not have to be elements included in the pivot table.

"REGION{,o=a,t=t}, DISTRICT{,o=a,t=t}"

In the example, the first row header is "REGION". It is sorted by "REGION", order is ascending, and type is text. The second row header is "DISTRICT". It is sorted by "DISTRICT", order is ascending, and type is text.

columns

This parameter defines the XML elements for column headers. The ordering information is specified within "{" and "}". The first attribute is the sort element. If not specified, the column header element is used as the sort element.

Supported attributes are:

  • o - specifies the sort order. Valid values are "a" for ascending or "d" for descending.

  • t - specifies the data type. Valid values are "t" for text or "n" for numeric.

You can specify more than one sort element, for example:

"emp-full-name {emp-lastname,o=a,t=n}{emp-firstname,o=a,t=n}"

sorts employee by last name and first name. Note that the sort element can be any element in the data set, and does not have to be included in the pivot table. In the preceding example, emp-lastname and emp-firstname do not have to be elements included in the pivot table.

"ProductsBrand{,o=a,t=t}, PeriodYear{,o=a,t=t}"

In the example, the first column header is "ProductsBrand". It is sorted by "ProductsBrand"; the order is ascending, and type is text. The second column header is "PeriodYear". It is sorted by "PeriodYear"; the order is ascending, and type is text.

measures

This parameter defines the XML elements used as measures.

"Revenue, PrevRevenue"

aggregation

This parameter specifies the aggregation function. Currently, the only supported value is "sum".

"sum"


Example

This example uses the following XML data:

- <ROWSET>
- <ROW>
  <ProductsType>COATINGS</ProductsType> 
  <ProductsBrand>Enterprise</ProductsBrand>   <Region>CENTRAL REGION</Region> 
  <District>CHICAGO DISTRICT</District> 
  <PeriodYear>1998</PeriodYear> 
  <Revenue>1555548.0</Revenue> 
  <PrevRevenue>125968</PrevRevenue> 
  <Units>11</Units> 
  </ROW>
...
</ROWSET>

The full data set includes four values for ProductsBrand, four values for Region, and two values for PeriodYear to be displayed in the pivot table.

Using the Template Builder for Word and the sample XML file you can create a pivot table as shown in figure Figure 5-22.

Figure 5-22 Template Builder Pivot Table Dialog

Surrounding text describes Figure 5-22 .

The generated XDO command for this pivot tables is as follows:

<?crosstab:c4536;"//ROW";"Region{,o=a,t=t},District{,o=a,t=t}";"PeriodYear{,o=a,t=t},ProductsBrand{,o=a,t=t}";"Revenue,PrevRevenue";"sum"?>

Running the command on the given XML data files generates this XML file "cttree.xml". Each XPath in the "cttree.xml" is described in the following table. The information in the table is to help you understand how BI Publisher constructs the pivot table. The generated cttree.xml file is not accessible for viewing or updating.

Element XPath Count Description

C0

/cttree/C0

1

This contains elements which are related to column.

C1

/cttree/C0/C1

4

The first level column "ProductsBrand". There are four distinct values. They are shown in the label H element.

CS

/cttree/C0/C1/CS

4

The column-span value. It is used to format the pivot table.

H

/cttree/C0/C1/H

4

The column header label. There are four distinct values "Enterprise", "Magicolor", "McCloskey" and "Valspar".

T1

/cttree/C0/C1/T1

4

The sum for measure 1, which is Revenue.

T2

/cttree/C0/C1/T2

4

The sum for measure 2, which is PrevRevenue.

C2

/cttree/C0/C1/C2

8

The first level column "PeriodYear", which is the second group-by key. There are two distinct values "2001" and "2002".

H

/cttree/C0/C1/C2/H

8

The column header label. There are two distinct values "2001" and "2002". Because it is under C1, the total number of entries is 4 x 2 = 8.

T1

/cttree/C0/C1/C2/T1

8

The sum for measure 1 "Revenue".

T2

/cttree/C0/C1/C2/T2

8

The sum for measure 2 "PrevRevenue".

M0

/cttree/M0

1

This contains elements that are related to measures.

M1

/cttree/M0/M1

1

This contains summary for measure 1.

H

/cttree/M0/M1/H

1

The measure 1 label, which is "Revenue".

T

/cttree/M0/M1/T

1

The sum of measure 1 for the entire Xpath from "//ROW".

M2

/cttree/M0/M2

1

This contains summary for measure 2.

H

/cttree/M0/M2/H

1

The measure 2 label, which is "PrevRevenue".

T

/cttree/M0/M2/T

1

The sum of measure 2 for the entire Xpath from "//ROW".

R0

/cttree/R0

1

This contains elements that are related to row.

R1

/cttree/R0/R1

4

The first level row "Region". There are four distinct values, they are shown in the label H element.

H

/cttree/R0/R1/H

4

This is the row header label for "Region". There are four distinct values "CENTRAL REGION", "EASTERN REGION", "SOUTHERN REGION" and "WESTERN REGION".

RS

/cttree/R0/R1/RS

4

The row-span value. It is used to format the crosstab table.

T1

/cttree/R0/R1/T1

4

The sum of measure 1 "Revenue" for each distinct "Region" value.

T2

/cttree/R0/R1/T2

4

The sum of measure 1 "Revenue" for each distinct "Region" value.

R1C1

/cttree/R0/R1/R1C1

16

This contains elements from combining R1 and C1. There are 4 distinct values for "Region", and four distinct values for "ProductsBrand". Therefore, the combination is 4 X 4 =16.

T1

/cttree/R0/R1/R1C1/T1

16

The sum of measure 1 "Revenue" for each combination of "Region" and "ProductsBrand".

T2

/cttree/R0/R1/R1C1/T2

16

The sum of measure 2 "PrevRevenue" for each combination of "Region" and "ProductsBrand".

R1C2

cttree/R0/R1/R1C1/R1C2

32

This contains elements from combining R1, C1 and C2. There are 4 distinct values for "Region", and four distinct values for "ProductsBrand", and two distinct values of "PeriodYear". Therefore, the combination is 4 X 4 X 2 = 32.

T1

/cttree/R0/R1/R1C1/R1C2/T1

32

The sum of measure 1 "Revenue" for each combination of "Region", "ProductsBrand" and "PeriodYear".

T2

/cttree/R0/R1/R1C1/R1C2/T2

32

The sum of measure 2 "PrevRevenue" for each combination of "Region", "ProductsBrand" and "PeriodYear".

R2

/cttree/R0/R1/R2

18

This contains elements from combining R1 "Region" and R2 "District". Because the list of values in R2 has dependency on R1, the number of entries is not just a simple multiplication.

H

/cttree/R0/R1/R2/H

18

The row header label for R2 "District".

R1N

/cttree/R0/R1/R2/R1N

18

The R2 position number within R1. This is used to check if it is the last row, and draw table border accordingly.

T1

/cttree/R0/R1/R2/T1

18

The sum of measure 1 "Revenue" for each combination "Region" and "District".

T2

/cttree/R0/R1/R2/T2

18

The sum of measure 2 "PrevRevenue" for each combination of "Region" and "District".

R2C1

/cttree/R0/R1/R2/R2C1

72

This contains elements from combining R1, R2 and C1.

T1

/cttree/R0/R1/R2/R2C1/T1

72

The sum of measure 1 "Revenue" for each combination of "Region", "District" and "ProductsBrand".

T2

/cttree/R0/R1/R2/R2C1/T2

72

The sum of measure 2 "PrevRevenue" for each combination of "Region", "District" and "ProductsBrand".

R2C2

/cttree/R0/R1/R2/R2C1/R2C2

144

This contains elements from combining R1, R2, C1 and C2, which gives the finest level of details.

M1

/cttree/R0/R1/R2/R2C1/R2C2/M1

144

The sum of measure 1 "Revenue".

M2

/cttree/R0/R1/R2/R2C1/R2C2/M2

144

The sum of measure 2 "PrevRevenue".


5.4.8.1 Inserting a Pivot Table in a Repeating Group

When you create a pivot table inside a repeating group you must manually edit the pivot table code so that the elements included in the pivot table respect the grouping context. The edit to the code depends on how you grouped the data.

If your data is flat and you used the Template Builder's Group By feature to group your data, use the "Procedure When Using the Template Builder "Group by" Feature". If the data is already grouped, use the "Procedure When the Data is Already Grouped".

Procedure When Using the Template Builder "Group by" Feature

After inserting the pivot table, open the BI Publisher Properties dialog to view the <?crosstab...?> code. In the crosstab command, update the "data-element" component to "current-group()".

For example, assume in the preceding example you created a repeating group around the pivot table that is grouped by the <Region> element.

To edit the pivot table code:

  1. Select and right-click the inserted pivot table. From the menu, select BI Publisher Properties to view the <?crosstab...?> command. Alternatively, open the Template Builder Field Browser and select the <?crosstab:...?> command.

  2. Replace the data-element component with "current-group()". For example, in the sample, the data-element value is "//ROW". Replace the value "//ROW" with "current-group()" as follows:

    <?crosstab:c4536;"current-group()";"Region{,o=a,t=t},District{,o=a,t=t}";"PeriodYear{,o=a,t=t},ProductsBrand{,o=a,t=t}";"Revenue,PrevRevenue";"sum"?>
    

    This applies the XDO crosstab command only across the current group to return the expected values in the pivot table.

Procedure When the Data is Already Grouped

If the data input to the Template Builder is already grouped, then you must insert the appropriate XPath for the data-element component to ensure that the pivot table only includes the elements in the current group.

For example, assume the data for this report is structured as follows:

<ROWSET> <REGION>
  <RegionName>CENTRAL REGION</RegionName> 
  <ProductList>
    <Product>
      <ProductsBrand>Enterprise</ProductsBrand> 
      <District>CHICAGO DISTRICT</District> 
      <PeriodYear>2001</PeriodYear> 
      <Revenue>1555548.0</Revenue> 
      <PrevRevenue>125968</PrevRevenue> 
      <Units>11</Units> 
   </Product

In your template you insert a repeating group based on the <REGION> element. When you insert the pivot table within the repeating group, the code appears as

<?crosstab:c10959;"//Product";"District{,o=a,t=t},ProductsBrand{,o=a,t=t}";"PeriodYear{,o=a,t=t}";"Revenue,PrevRevenue";"sum"?>

In this case, to instruct BI Publisher to use only the elements under the current REGION grouping, edit the data-element to use the relative XPath as follows: ".//Product". The edited code is:

<?crosstab:c10959;".//Product";"District{,o=a,t=t},ProductsBrand{,o=a,t=t}";"PeriodYear{,o=a,t=t}";"Revenue,PrevRevenue";"sum"?>

5.4.9 Inserting and Editing Conditional Regions

A conditional region is an area that is surrounded by a conditional statement. If the statement tests true, the area is displayed in the report; if the condition tests false, the area is suppressed from the report.

For example, the data contains sales information. The report contains a table that displays sales by industry. You want this table in the report to display information for industries with sales amounts lower than 100,000. Using the insert conditional region functionality, you can select the region that contains the sales table and insert the condition that the sales element must be less than 100,000.

  1. Select the region that you want to apply the condition to. For example, if you want to display a table only for a certain condition, then select the region that contains the table. Note that the region must be inside a loop.

  2. On the Oracle BI Publisher menu, on the Insert group, click Conditional Region. Figure 5-23 shows the BI Publisher Properties dialog for a Conditional Region.

    Figure 5-23 The BI Publisher Properties Dialog for a Conditional Region

    Description of Figure 5-23 follows
    Description of "Figure 5-23 The BI Publisher Properties Dialog for a Conditional Region"

  3. Enter the following fields:

    Data Field - Select the field to test for the condition. Select the data type of the field: Number or Date/Text.

    (Condition 1) Data field - Select the comparison operator.

    Select the value to meet the condition. Note that you can enter an integer, enter text, or select another data element to define a comparison based on the incoming values.

  4. Click OK. The form fields that contain the conditional logic are inserted around the region. The beginning form field displays the text "C" and the form field closing the region displays the text "EC".

To edit the conditional region, double-click the inserted form field to launch the dialog for editing; or, right-click the form field and select BI Publisher, then Properties.

5.4.10 Inserting Conditional Formatting

Using the Conditional Format feature you can insert simple conditional formats to apply to table rows or cells. The dialog provides several common options that you can select and the Template Builder inserts the code automatically. The Conditional Format dialog supports two conditions per field.

Note:

The Conditional Format dialog cannot be used inside of pivot tables. You must insert the conditional formatting logic directly to the appropriate form fields.

To insert a conditional format:

  1. Place the cursor in the table cell of the data element for which you want to define the condition.

  2. On the Oracle BI Publisher menu, on the Insert group, click Conditional Format. Figure 5-24 shows the BI Publisher Properties dialog for a Conditional Format.

    Figure 5-24 The BI Publisher Properties dialog for a Conditional Format

    Description of Figure 5-24 follows
    Description of "Figure 5-24 The BI Publisher Properties dialog for a Conditional Format"

  3. Enter the following in the Conditional Format dialog

    Data Field - Select the element to test for the condition and the data type of the element (Number or Date/Text).

    Apply to Entire Table Row - If you want the format applied to the entire table row, not just the cell of the selected element, then select this box.

    Condition 1) Data field - Select the comparison operator.

    Select the value to meet the condition. You can enter an integer, enter text, or select another data element to define a comparison based on the incoming values.

  4. Click Format to define the format you want to apply when the condition is met. Options are background color, font color, and font style (regular, bold, italic, bold italic). Select the box and format of each option you want to apply. After you select the format, the Preview region displays the format chosen.

    Figure 5-25 shows the Format dialog.

    Figure 5-25 The Format Dialog

    Description of Figure 5-25 follows
    Description of "Figure 5-25 The Format Dialog"

  5. Define a second condition if desired.

  6. Click OK. The conditional format field is inserted as a form field with the display text "C".

To edit the conditional format, double-click the inserted form field to launch the dialog for editing; or, right-click the form field and select BI Publisher, then Properties.

5.5 Previewing a Template

The Preview menu group enables you to preview the RTF template with sample XML data.

Note:

If you have not already done so, then you must load sample data to the Template Builder to preview the report. See Section 5.3, "Accessing Data for Building Templates."

From the Preview group, select the output format. If you have not yet saved the template as an RTF file, then you are prompted to do so.

5.6 Template Editing Tools

This section describes additional tools provided with the Template Builder to help you validate and edit the template. This section includes:

5.6.1 Editing and Viewing Field Properties

Once you have inserted a data field (see Section 5.4.1, "Inserting a Field") you can view or edit the field properties in the BI Publisher Properties dialog.

To invoke the BI Publisher Properties dialog, perform one of the following:

  • Double-click the field

  • Right-click the field, from the menu select BI Publisher, then Properties

Figure 5-26 shows the BI Publisher Properties dialog: note the Properties tab, the Advanced tab, and the Word Properties button. Some fields might display only the Advanced tab.

Figure 5-26 The BI Publisher Properties Dialog

Description of Figure 5-26 follows
Description of "Figure 5-26 The BI Publisher Properties Dialog"

5.6.1.1 About the Properties Tab

You can set the following properties for a data field:

Data Field - Select the data field from the list of available fields from the loaded data source.

Text to Display - Enter the display text for the form field in the template. This text is replaced at runtime by the value in the data.

Type - Select the type of data. Options are Regular Text, Number, Date, Current Date, Current Time. The selection in this field determines the format options.

Format - For any data type except Regular Text, you can select from several number or date display formatting masks or enter your own.

Force LTR - (Force Left-to-Right) Use this check box when you are publishing the template in a language that prints the characters from right to left, such as Arabic or Hebrew. Use this option to force left-to-right printing for fields such as phone numbers, addresses, postal codes, or bank account numbers.

Function - This feature enables you to perform aggregation functions (Sum, Average, Count, Minimum, Maximum) on data fields. For example, if you select sum for a data field, then the field shows the sum of all occurring values for this data field depending on the scope (see below). See also Section 5.4.1, "Inserting a Field" for information on aggregation functions.

Scope (informational only) - This field has two possible values:

  • Group Item - Indicates that the data field is inside a group. If you choose to perform a function on the field, then only the occurrences of the field within the current group are included in the aggregation.

  • Normal - Indicates that the field is not inside a group. Aggregation functions are performed on all occurrences of the field in the data.

5.6.1.2 About the Advanced Tab

The Advanced tab displays the underlying code. If the code pattern within the form field is not recognized (for example, because you added commands manually to the field), then the BI Publisher Properties dialog displays this tab only.

Use this tab to edit or add code to the form field manually. Click OK to update the template. Figure 5-27 shows the Advanced tab.

Figure 5-27 The BI Publisher Properties Dialog: Advanced Tab

Description of Figure 5-27 follows
Description of "Figure 5-27 The BI Publisher Properties Dialog: Advanced Tab"

5.6.1.3 About the Word Properties Button

The Word Properties button opens the Microsoft Word Text Form Field Options dialog. You can also use this dialog to set the data type and number format. The underlying code used by BI Publisher is also available by clicking the Add Help Text button.

5.6.2 Validating a Template

The Template Builder provides a validation tool to check the template for incorrect use of BI Publisher commands and unsupported elements in the RTF file.

To validate the template:

  1. On the BI Publisher menu, on the Tools group, click Validate Template.

If there are no validation errors, then a "No Error found" message is returned. If an error is found, then an error message is displayed. You can use the Field Browser to help locate the error.

5.6.3 Using the Field Browser

The field browser dialog provides a fast way to review and update the BI Publisher instructions hidden in the Microsoft Word form fields. This dialog is particularly useful to understand and modify existing templates.

On the Tools group, click Field Browser.

Figure 5-28 shows the Field Browser dialog.

Figure 5-28 The Field Browser Dialog

Description of Figure 5-28 follows
Description of "Figure 5-28 The Field Browser Dialog"

The Field Browser dialog shows a table with the display text of the form field in the Text column and the underlying code instructions in the second Code column. When you select a specific row in the dialog, the matching form field is selected in the Microsoft Word document.

If you select some part of the text before opening the Field Browser, then the dialog shows only the fields in the selection. If no text is selected, then the field browser shows all fields in the document.

The options in the Field Browser are described in the Table 5-2.

Table 5-2 Field Browser Options

Option Description

Edit

You can update processing instructions directly from the Field Browser dialog. Select a field in the Text table. The Edit box shows the processing instructions for the field. To change the instructions for the field modify the text in the Edit field and click Update.

Refresh

The Field Browser dialog is not aware of any form fields that you have added or modified while the dialog is open. Click Refresh to show any changes to the document since the Field Browser dialog has been opened.

Show All

If you opened the browser with a part of the document selected, then you see only the form fields in the selected area. Click Show All to see all the form fields in the document.

Close

Click Close to close the field property browser. The only button does not automatically update any changes in the edit field, therefore ensure that you select Update if you want to save edits.


5.6.4 Checking Accessibility

The Template Builder provides an accessibility checker to check the template for features to enhance the accessibility of the report for report consumers who may need assistive technologies to view the report.

To check for the presence of accessibility features: On the BI Publisher tab, in the Tools group, click Check Accessibility. The tool generates a report that indicates areas of a template that do not include the following accessibility features:

  • document title

  • alternative text for images

  • table summary for data tables

  • column header for data tables

  • row header for data tables

In some cases the accessibility checker cannot determine if the accessibility feature is present and generates a warning. The report designer can then verify that the accessibility features are present.

For information on how to add these features to the template, see Appendix C, "Designing Accessible Reports."

5.7 Uploading a Template to the BI Publisher Server

If you used the Open Template dialog to connect to BI Publisher, and load the data to the Template Builder, or if you downloaded an existing template from the BI Publisher catalog, then you can upload the new or updated layout back to the report definition on the server. See Section 5.2.2.1, "Working in Connected Mode."

If you downloaded an existing template and want to upload the modifications to the template, then select Upload Template from the Oracle BI Publisher menu.

If this is a new template for the report definition, then use the Upload Template As option to upload the layout to the report definition on the server. Also use this option to upload modifications to an existing template under a different name.

5.8 Using the Template Builder Translation Tools

The Template Builder provides tools to help you create and test translations for templates.

5.8.1 About Translations

There are two options for adding translated templates to a BI Publisher report definition:

  • Create a separate RTF template that is translated (a localized template)

  • Generate an XLIFF file from the original template (at runtime the original template is applied for the layout and the XLIFF file is applied for the translation)

Use the first option if the translated template requires a different layout from the original template.

If you only require translation of the text strings of the template layout, use the XLIFF option.

For detailed information, see Chapter 15, "Translation Support Overview and Concepts."

To use the Template Builder translation tools to create templates for translations, see the following topics in this section:

  • Extracting Text to an XLIFF File for Translation

  • Previewing a Translation

  • Localizing a Template

For a demo on BI Publisher's localization capabilities, see the LocalizationDemo.exe demo provided with the Template Builder installation (located in the BI Publisher\BI Publisher Desktop\demos folder where you installed BI Publisher Desktop).

5.8.2 Extracting Text to an XLIFF File for Translation

This menu item allows you to create a standard XLIFF translation file that contains the boilerplate text from the template. XLIFF is a standard file format that is understood by many translation software packages. Since an XLIFF is an XML file, you can translate the text in a regular text editor.

A "translatable string" is any text in the template that is intended for display in the published report, such as table headers and field labels. Text supplied at runtime from the data is not translatable, nor is any text that you supply in the Microsoft Word form fields.

To extract text to an XLIFF file for translation:

  1. From the BI Publisher menu, select Tools, then Translate Template, then Extract Text.

  2. You are prompted to save the extract file as an XML file type. Enter a name for the extract file and save to the desired location.

  3. If you want to translate the template manually, open the .xlf file using a text editor and enter the translated strings in the file. For a detailed description of working with the BI Publisher generated .xlf files, see Section 15.2, "Working with Translation Files."

  4. When done, you can preview the translation. Then upload the file to the BI Publisher report definition.

5.8.3 Previewing the Template and Translation File

To preview the template with the translated XLIFF file applied:

  1. From the BI Publisher, in the Tools group, click Translation, then Preview Translation.

  2. You are prompted to select the saved XLIFF file. Locate the file, and click Open.

The Template Builder merges the sample data, the translation file, and the RTF template to generate a PDF for preview.

5.8.4 Localizing a Template

Localizing a template means that you are creating a template to be used for a specific language.

Because BI Publisher enables you to extract the boilerplate text strings from a template into an XLIFF file that can be translated and then applied at runtime, if the reports for additional languages only require the translation of these text strings, then you only need to supply translated XLIFF files to accompany the base template.

However, you would localize a template when the requirements for the report in the specific language go beyond the simple translation of the text in the layout.

To save a template as a localized template:

  1. From the Oracle BI Publisher menu, in the Tools group, select Translations, then Localize Template. This invokes a warning message that localizing the template overwrites the template. Click OK.

  2. You are prompted to select the XLIFF translation file. Locate the appropriate file and click Open.

    The translated XLIFF file is applied to the template that you currently have open in Microsoft Word.

  3. Save the localized template.

  4. Upload the template file to the appropriate report definition in the BI Publisher catalog. Select the appropriate locale in the upload dialog.

5.9 Setting Options for the Template Builder

Access the Options dialog as follows: In the Options group, click Options.

The Options dialog contains four tabs: UI, Preview, Build, and Connection, as described in the following sections.

5.9.1 Setting UI Options

Use the Options dialog: UI tab to set options that influence the look and feel of the Template Builder.

Figure 5-29 shows the Options dialog: UI tab.

Figure 5-29 Options Dialog: UI Tab

Description of Figure 5-29 follows
Description of "Figure 5-29 Options Dialog: UI Tab"

The tree view that shows the data source can show either the correct XML tag names of the data source or they can show a slightly modified version that is easier to read. Select the option Element Names for Report XML to show the modified labels. These labels contain no <> characters, use "Title case" and use spaces (" ") instead of underscores ("_").

5.9.2 Setting Preview Options

The Options dialog: Preview tab allows you to specify options that influence the Preview functionality of the Template Builder.

Figure 5-30 shows the Options dialog: Preview tab.

Figure 5-30 The Options Dialog: Preview Tab

Description of Figure 5-30 follows
Description of "Figure 5-30 The Options Dialog: Preview Tab"

Table 5-3 describes the options available from the Preview tab.

Table 5-3 Preview Options

Option Description

Style Template

If you have a BI Publisher Style Template available locally, then you can specify it here. A style template is an RTF template that contains style information that can be applied to RTF layouts, similar to a style sheet. The style information in the style template is applied to RTF layouts at runtime to achieve a consistent look and feel across your enterprise reports. For more information, Chapter 11, "Creating and Implementing Style Templates."

Locale

You can choose the language and territory used for previewing the template. While this change does not automatically translate any files, it is important to set the correct locale for the preview to use the correct direction of the text (left-to-right or right-to-left), and to correctly set locale-specific date, number, and currency formats.

Java Home

The Preview (and export functionality) requires Java code. You can change the path to the JAVA HOME directory. If this option is not specified, the Template Builder assumes that the Java virtual machine (java.exe) is accessible in the PATH specified in the environment variables of Windows.

Java Option

Specify the memory to reserve for the Template Builder to process the template. The default value is -Xmx256M.


5.9.3 Setting Build Options

Use the Options dialog: Build tab to specify options that influence how the Template Builder generates tables and forms.

Figure 5-31 shows the Options dialog: Build tab.

Figure 5-31 The Options Dialog: Build Tab

Description of Figure 5-31 follows
Description of "Figure 5-31 The Options Dialog: Build Tab"

Table 5-4 describes the options available from the Build tab.

Table 5-4 Build Tab Options

Option Description

For-each form field

Select how the Template Builder creates the form fields for processing instructions in the Insert Table/Form dialog.

The Descriptive option (for example: for-each Invoice) renders a descriptive form field for the processing instructions. This option makes the layout template easier to understand. However, the longer fields may distract from the visual layout of the template. Note that the descriptive option does not apply to fields within table cells.

The Abbreviated option (for example: F) provides a one letter abbreviation for each instruction.

Select the Hidden box to generate the processing instruction form fields using Microsoft Word's hidden font effect. Hidden text is hidden in the Print Preview and you may display or hide the hidden text by changing the Hidden Text setting in the Display group of the Microsoft Word Options.

Form Field Size

Large - inserts the BI Publisher code to a document variable. The document variable field can accommodate approximately 48 kilobytes of code line.

It is important to note that this setting affects only fields that are created or edited while this option is set. The form fields created with the Large setting cannot be understood by Oracle BI Publisher 10g. If the template is intended for use with the 10g version of BI Publisher, use the Backward Compatibility setting.

Backward Compatible - in previous versions of the Template Builder the BI Publisher code was inserted to the Microsoft Word Form Field Help Text box. This limited the length of code that could be inserted for a single form field. By default, the Large option is used because it can accommodate much larger code strings. However, the Large option is not compatible with Oracle BI Publisher 10g.

Table Header Color

When you insert a table using the Table Wizard or the Insert Table/Form dialog the Template Builder applies the Table Header Color specified here to the table header background. Customize the default color for the templates.

Generate XSLT 2.0 compliant code

BI Publisher uses the XSLT processor provided by Oracle XDK 11.1.0.7.0, which supports the W3C XSL Transformations 1.0 recommendation. The processor also implements the current working drafts of the XSLT and XPath 2.0 standards. For more information about Oracle XDK, see Oracle XML Developer's Kit Programmer's Guide.

By default, BI Publisher is compatible with XSLT 1.0. If you want to use XSLT and XPath 2.0 features in the template, then enable this option. This configuration is performed at the template level. The template-level setting overrides the server setting.


5.9.4 Setting Connection Options

Options on this tab are reserved for a future release.

5.10 Setting Up a Configuration File

The Template Builder can be used with a BI Publisher configuration file.

The configuration file must be named xdoconfig.xml and must be stored in the config directory (example path: C:\Program Files\Oracle\BI Publisher Desktop\Template Builder for Word\config) under the BI Publisher directory.

Alternatively, you can use the file name xdo.cfg, which is used by the BI Publisher server. The configuration file allows you to:

See the appendix "Configuration File Reference" in Oracle Fusion Middleware Administrator's Guide for Oracle Business Intelligence Publisher for the syntax of the configuration file.

5.11 BI Publisher Menu Reference

When you install the Template Builder the next time you open Microsoft Word, you see the Oracle BI Publisher menu.

Note:

If you are using Microsoft Word 2007, then you might have to modify the Add-In settings. Click the Office Button, click Word Options, then click Add-Ins.

5.11.1 About the Online Group

The Online group of commands enable you to initiate interaction with the BI Publisher application. For more information about working with the online commands, see Section 5.2.2.1, "Working in Connected Mode."

Figure 5-32 shows the Online group of commands.

Figure 5-32 The Online Group of Commands

Description of Figure 5-32 follows
Description of "Figure 5-32 The Online Group of Commands"

Table 5-5 describes the commands available for the Online group.

Table 5-5 Online Group Commands

Command Description

Log on

Enables you to log in to BI Publisher. Enter your user name and password. Select or enter the URL for the BI Publisher Report Server (see your Administrator if you do not know the URL). When you log on, the Open Template dialog is displayed.

Note: You must log in directly to the BI Publisher server. For example: http://www.example.com:7001/xmlpserver.

Open

After you log on, this command becomes available to enable you to open a report in the BI Publisher catalog.

Upload Template

If you used the Open Template dialog to download a template from the BI Publisher catalog, use this option to upload the updated layout back to the report definition in the catalog.

Upload Template As

If you used the Open Template dialog to download a template or to open a report from the catalog, use this option to upload the layout to the report definition in the catalog. Also use this option to upload modifications to an existing template under a different name.

Save XML Data

If you are working in connected mode, then use this command to save the data to a local directory if you also need access to the data in disconnected mode.


5.11.2 About the Load Data Group

The Load Data group of commands enables you to load a saved sample data file or sample schema to the Template Builder. You must load data to use most of the Template Builder functionality. See Section 5.3, "Accessing Data for Building Templates" for more options for loading data to the Template Builder.

Figure 5-33 shows the Load Data group of commands.

Figure 5-33 The Load Data Group of Commands

Description of Figure 5-33 follows
Description of "Figure 5-33 The Load Data Group of Commands"

Table 5-6 describes the commands available for the Load Data group.

Table 5-6 Load Data Group Commands

Command Description

Sample XML

This command enables you to load a previously saved sample XML file from the report data source. If you are not connected to the BI Publisher server, use this method to load the data.

XML Schema

This command enables you to load an XML Schema file (.xsd) that contains the fields available in the report XML data. The XML schema has the advantage of being complete (a sample xml file may not contain all the fields from the data source). For the preview, the Template Builder can generate dummy sample data for an XML Schema. However, the preview works better if you also upload real sample data.


5.11.3 About the Insert Group

Use the Insert group of commands to insert the layout components to the template. For more information, see Section 5.4, "Inserting Components to the Template."

Figure 5-34 shows the Insert group of commands.

Figure 5-34 The Insert Group of Commands

Description of Figure 5-34 follows
Description of "Figure 5-34 The Insert Group of Commands"

Table 5-7 describes the commands available for the Insert group.

Table 5-7 Insert Group Commands

Command Description

Table Wizard

This function provides a wizard that guides you through the creation of tables used in typical reports.

Pivot Table

The Pivot Table function enables you to drag and drop the data elements to a pivot table structure.

Chart

BI Publisher does not recognize native Microsoft Word charts. The Insert Chart function allows you to insert a chart that is understood by Oracle BI Publisher.

Field

This function allows you to select fields from the data source and insert them into the template.

Note: As a beginner, you should use Insert Fields only for data fields that are unique - none repeating - in the document. See Section 5.4.2, "Inserting a Table Using the Table Wizard" for additional information on how to insert repetitive fields.

Table/Form

Use this function to insert data fields to be organized as a simple or nested table or as a form that is repeated with different data. You may even organize all the data fields for the whole document before inserting them.

Repeating Group

Enables you to select or define a group of elements that you want repeated for each occurrence of an element in the data.

Conditional Format

Enables you to define simple conditional formats to apply to table rows or cells.

Conditional Region

Enables you to insert a conditional statement around a region of the template.

All Fields

This function inserts all fields found in the XML data into the document. It also inserts processing instructions into the document that repeats a section - such as a table row - when the associated XML element is repeated.

Note: XML documents often contain a large number of fields in a deeply nested hierarchy. For example, an Oracle Purchasing purchase order contains purchase order lines, which contain shipments, which contain distributions. The purchase order line alone contains more than 150 data fields. In these cases, you should use the Insert Table/Form function to have more control over which fields are inserted.


5.11.4 About the Preview Group

The Preview group of commands enables you to preview the RTF template with the sample XML data. The preview menu offers PDF, HTML, RTF, PowerPoint, Excel (MHTML format) and EXCEL2000 as output formats. When you select any of these output formats, the Template Builder merges the data into the template and creates the output document.

Figure 5-35 shows the Preview group of commands.

Figure 5-35 The Preview Group of Commands

Description of Figure 5-35 follows
Description of "Figure 5-35 The Preview Group of Commands"

Note:

You must have Adobe Acrobat Reader version 5.0 or higher installed to preview documents in PDF format.

5.11.5 About the Tools Group

For more information about using the commands in the Tools group refer to Section 5.6, "Template Editing Tools" and Section 5.8, "Using the Template Builder Translation Tools."

Figure 5-36 shows the Tools group of commands.

Figure 5-36 The Tools Group of Commands

Description of Figure 5-36 follows
Description of "Figure 5-36 The Tools Group of Commands"

Table 5-8 describes the commands available for the Tools group.

Table 5-8 Tools Group Commands

Command Description

Field Browser

The field browser is a tool for advanced users who must change the BI Publisher commands that are hidden in the form fields. It shows the commands behind each form field and allows you to change them. Use this tool to correct flawed RTF templates or to update multiple fields efficiently.

Validate Template

The validation function checks the template for incorrect use of BI Publisher commands and unsupported elements in the Word file.

Translation

Includes the following subcommands:

  • Extract Text - Enables you to create a standard XLIFF translation file that contains the boilerplate text from the template. XLIFF is a standard file format that is understood by many translation software packages. Because an XLIFF is an XML file, you can translate the text in a text editor. For more information on working with XLIFF files, see Section 15.2, "Working with Translation Files."

  • Preview Translation - Enables you to preview the template as a PDF file using a specified XLIFF translation file. This functionality enables you to test translation files.

  • Localize Template - Applies a translation file to an RTF template. This means that in the current RTF template all boilerplate text is translated. The main function of this feature is to create a language-specific version of a template.

Export

Includes the following functions:

  • XSL-FO Stylesheet - Allows you to convert the RTF template into an enhanced XSL-FO stylesheet. This function can be used to generate XSL-FO for debugging or further customization.

  • Formatted XML - Enables you to apply the XSL-FO stylesheet generated from the Word document to the sample data and save the intermediate FO format. This function is mainly for debugging.

  • PDF - Converts the Word document to PDF.


5.11.6 About the Options Group

The Options group of commands allows you to define preferences and options for using BI Publisher and access online help.

Figure 5-37 shows the Options group of commands.

Figure 5-37 The Options Group of Commands

Description of Figure 5-37 follows
Description of "Figure 5-37 The Options Group of Commands"

See Section 5.9, "Setting Options for the Template Builder."