BI Publisher Advanced RTF Template Image, Chart and Graph Techniques

Images and Charts

Oracle BI Publisher supports several methods of including images or charts in an Oracle BI Publisher report.

•       Direct insertion

•       URL reference

•       OA_MEDIA directory reference

•       Image retrieved from BLOB data

•       Leveraging Oracle Business Intelligence Beans (UI Beans) to add charts and graphs to an RTF template.

Images and Charts

For URL reference, do the following:

1. Insert a dummy image in your template. For layout purposes, it is best if the dummy image is the same size, in pixel height and width, as your actual image.
2. In the Format Picture dialog box (right-click on the image to open), select the Web tab. Enter the following syntax in the Alternative Text region: url:{‘http://image.location.com/image-name’}

OA_MEDIA method refers to only Oracle eBusiness Suite installations. Otherwise, it is the same at the URL reference with the Alternative Text changing to: url:{‘${OA_MEDIA}/image-name’}

If your data source is an Oracle BI Publisher Data Template, and your results XML contains image data that had been stored as a BLOB in the database, use the following syntax in a form field inserted in your template where you want the image to render at run time:

<fo:instream-foreign-object content type="image/jpg">

<xsl:value-of select="IMAGE_ELEMENT"/>

</fo:instram-foreign-object>

where image/jpg is the MIME type of the image (other options might be: image/gif and image/png)

And IMAGE_ELEMENT is the element name of the BLOB in your XML data.

Note that you can specify height and width attributes for the image to set its size in the published report. Oracle BI Publisher will scale the image to fit the box size that you define. For example, to set the size of the example above to three inches by four inches, enter the following:

<fo:instream-foreign-object content type="image/jpg" height="3 in

" width="4 in">

<xsl:value-of select="IMAGE_ELEMENT"/>

</fo:instram-foreign-object>

Specify in pixels as follows:

<fo:instream-foreign-object content type="image/jpg" height="300

px" width="4 px">

...

or in centimeters:

<fo:instream-foreign-object content type="image/jpg" height="3 cm

" width="4 cm">

...

or as a percentage of the original dimensions:

<fo:instream-foreign-object content type="image/jpg" height="300%

" width="300%">

...

Adding a Chart

•       Insert a dummy image in your template to define the size and position of the chart.

•       Add a definition for the chart to the Alternative Text box of the dummy image. The chart definition requires XSL commands.

•       At run time, Oracle BI Publisher calls the appropriate BI Bean to render the image that is insert into the final output.

Adding a Chart

Note: For more information, see pg. 2–16 through 2–26 in the Oracle BI Publisher User’s Guide.

The process generates a placeholder. The text of that placeholder can be viewed by right-clicking the image placeholder, choosing Fomat Picture, and then selecting the Web tab.

Chart Sample: Bar Chart

 

  

Chart Sample: Bar Chart

There are only four supported chart types.

•          Bar

•          Pie

•          Bar – Horizontal

•          Line

 

Chart Sample: Pie Chart

 

Chart Sample: Line Chart

 

Background and Watermark Support

Oracle BI Publisher supports the Background feature in Microsoft Word. You can specify a single, graduated color or an image background for your template to be displayed in the PDF output. Note that this feature is supported for PDF output only.

To add a background to your template, use the Format > Background menu option.

In Microsoft Word 2002 or later, you can add a text or image watermark via Format > Background > Printed Watermark.

Template Features

•       Page breaks

•       Initial page numbers

•       Hyperlinks

•       Table of contents

•       Bookmarks in PDF output

•       Check boxes

•       Drop-down lists

Template Features

Page Breaks

To create a page break after the occurrence of a specific element, use the split-by-page-break alias. This will cause the report output to insert a hard page break between every instance of a specific element. You can also insert a form field immediately following the form field of the element you want the page break to occur after. In the Help Text of this form field, enter the syntax:

•          <?split-by-page-break:?>

Initial Page Numbers

Some reports require that the initial page number be set at a specified number. For example, monthly reports may be required to continue numbering from month to month. Oracle BI Publisher allows you to set the page number in the template to support this requirement.

Use the following syntax in your template to set the initial page number:

•          <?initial-page-number:pagenumber?>

where pagenumber is the XML element or parameter that holds the numeric value.

If your XML data contains an element to carry the initial page number, for example:

<REPORT>

    <PAGESTART>200<\PAGESTART>

    ....

</REPORT>

Enter the following in your template:

•          <?initial-page-number:PAGESTART?>

Your initial page number will be the value of the PAGESTART element, which in this case is 200.

Example 2: Set page number by passing a parameter value.

If you define a parameter called PAGESTART, you can pass the initial value by calling the parameter.

Enter the following in your template:

•          <?initial-page-number:$PAGESTART?>

Note: You must first declare the parameter in your template. See “Defining Parameters in Your Template” in the Oracle BI Publisher User’s Guide.

Hyperlinks

You can add fixed or dynamic hyperlinks to your template.

•          To insert static hyperlinks, use your word-processing application’s insert hyperlink feature.

•          If your template includes a data element that contains a hyperlink or part of one, you can create dynamic hyperlinks at run time. In the Type the file or Web page name field of the Insert Hyperlink dialog box, enter the following syntax:

{URL_LINK}

where URL_LINK is the incoming data element name.

•          If you have a fixed URL that you want to pass parameters to, enter the following syntax:

http://www.oracle.com?product={PRODUCT_NAME}

where PRODUCT_NAME is the incoming data element name.

•          In both these cases, at run time the dynamic URL will be constructed.

Table of Contents

Oracle BI Publisher supports the table of contents generation feature of the RTF specification. Follow your word-processing application’s procedures for inserting a

table of contents. Oracle BI Publisher also provides the ability to create dynamic section headings in your document from the XML data. You can then incorporate these into a table of contents.

To create dynamic headings:

1. Enter a placeholder for the heading in the body of the document, and format it as a “Heading,” using your word-processing application’s style feature. You cannot use form fields for this functionality.

·   For example, you want your report to display a heading for each company reported. The XML data element tag name is <COMPANY_NAME>. In your template, enter <?COMPANY_NAME?> where you want the heading to appear. Now format the text as a Heading.

2. Create a table of contents using your word-processing application’s table of contents feature.
3. At run time, the TOC placeholders and heading text will be substituted.

Generating Bookmarks in PDF Output

If you have defined a table of contents in your RTF template, you can use your table of contents definition to generate links in the Bookmarks tab in the navigation pane of your output PDF. The bookmarks can be either static or dynamically generated.

•          To create links for a static table of contents, enter the syntax:

<?copy-to-bookmark:?>

directly above your table of contents and

<?end copy-to-bookmark:?>

directly below the table of contents.

•          To create links for a dynamic table of contents, use:

<?convert-to-bookmark:?>

directly above the table of contents and

<?end convert-to-bookmark:?>

directly below the table of contents.

Check Boxes

You can include a check box in your template that you can define to display as selected (Checked) or deselected (Not Checked) based on a value from the incoming data. To define a check box in your template:

1. Position the cursor in your template where you want the check box to appear, and select the Check Box Form Field from the Forms tool bar.
2. Right-click the field to open the Check Box Form Field Options dialog box.
3. Specify the Default value as either Checked or Not Checked.
4. In the Form Field Help Text dialog box, enter the criteria for how the box should behave. This must be a Boolean expression (that is, one that returns a true or false result). For example, suppose your XML data contains an element called <population>. You want the check box to appear selected if the value of <population> is greater than 10,000. Enter the following in the help text field: <?population>10000?>
5. Note that you do not have to construct an “if” statement. The expression is treated as an “if” statement.

Drop-Down Lists

Oracle BI Publisher allows you to use the drop-down form field to create a cross-reference in your template from your XML data to some other value that you define in the drop-down form field. For example, suppose you have the following XML:

<countries>

    <country>

        <name>Chad</name>

        <population>7360000</population>

        <continentIndex>5</continentIndex>

    </country>

    <country>

        <name>China</name>

        <population>1265530000</population>

        <continentIndex>1</continentIndex>

    </country>

    <country>

        <name>Chile</name>

        <population>14677000</population>

        <continentIndex>3</continentIndex>

    </country>

    . . .

</countries>

Notice that each <country> entry has a <continentindex> entry, which is a numeric value to represent the continent. Using the drop-down form field, you can create an index in your template that will cross-reference the <continentindex> value to the actual continent name. You can then display the name in your published report. To create the index for the continent example:

1. Position the cursor in your template where you want the value from the drop-down list to display, and select the Drop-Down Form Field from the Forms tool bar.
2. Right-click the field to display the Drop-Down Form Field Options dialog box.
3. Add each value to the Drop-down item field and the click Add to add it to the Items in drop-down list group. The values will be indexed starting from one for the first, and so on. For example, the list of continents will be stored as follows:

Index    Value

1                              Asia

2                              North America

3                              South America

4                              Europe

5                              Africa

6                              Australia

Now use the Help Text box to enter the XML element name that will hold the index for the drop-down field values. For this example, enter <?continentIndex?>

== Mohan G