Skip Headers

Oracle Business Intelligence Publisher User's Guide
Release 10.1.3.2

Part Number B40017-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

Skip Headers

Oracle Business Intelligence Publisher User's Guide
Release 10.1.3.2
Part Number B40017-01
Go to Table of Contents
Contents
Go to previous page
Previous
Go to next page
Next

Creating a PDF Template

Overview

To create a PDF template, take any existing PDF document and apply the BI Publisher markup. Because the source of the PDF document does not matter, you have multiple design options. For example:

Note: The steps required to create a template from a third-party PDF depend on whether form fields have been added to the document. For more information, see Creating a Template from a Predefined PDF Form.

If you are designing the layout, note that once you have converted to PDF, your layout is treated like a set background. When you mark up the template, you draw fields on top of this background. To edit the layout, you must edit your original document and then convert back to PDF.

For this reason, the PDF template is not recommended for documents that will require frequent updates to the layout. However, it is appropriate for forms that will have a fixed layout, such as invoices or purchase orders.

Supported Modes

BI Publisher supports Adobe Acrobat 5.0 (PDF specification version 1.4). If you are using Adobe Acrobat Professional 6.0 (or later), use the Reduce File Size Option (from the File menu) to save your file as Adobe Acrobat 5.0 compatible.

For PDF conversion, BI Publisher supports any PDF conversion utility, such as Adobe Acrobat Distiller.

Designing the Layout

To design the layout of your template you can use any desktop application that generates documents that can be converted to PDF. Or, scan in an original paper document to use as the background for the template.

The following is the layout for a sample purchase order. It was designed using Microsoft Word and converted to PDF using Adobe Acrobat Distiller.

the picture is described in the document text

The following is the XML data that will be used as input to this template:

<?xml version="1.0"?>
<POXPRPOP2>
 <G_HEADERS>
  <POH_PO_NUM>1190-1</POH_PO_NUM>
  <POH_REVISION_NUM>0</POH_REVISION_NUM>
  <POH_SHIP_ADDRESS_LINE1>3455 108th Avenue</POH_SHIP_ADDRESS_LINE1>
<POH_SHIP_ADDRESS_LINE2></POH_SHIP_ADDRESS_LINE2>
<POH_SHIP_ADDRESS_LINE3></POH_SHIP_ADDRESS_LINE3>
<POH_SHIP_ADR_INFO>Seattle, WA 98101</POH_SHIP_ADR_INFO>
<POH_SHIP_COUNTRY>United States</POH_SHIP_COUNTRY>
<POH_VENDOR_NAME>Allied Manufacturing</POH_VENDOR_NAME>
<POH_VENDOR_ADDRESS_LINE1>1145 Brokaw Road</POH_VENDOR_ADDRESS_LINE1>
<POH_VENDOR_ADR_INFO>San Jose, CA 95034</POH_VENDOR_ADR_INFO>
<POH_VENDOR_COUNTRY>United States</POH_VENDOR_COUNTRY>
<POH_BILL_ADDRESS_LINE1>90 Fifth Avenue</POH_BILL_ADDRESS_LINE1>
<POH_BILL_ADR_INFO>New York, NY 10022-3422</POH_BILL_ADR_INFO>
<POH_BILL_COUNTRY>United States</POH_BILL_COUNTRY>
<POH_BUYER>Smith, J</POH_BUYER>
<POH_PAYMENT_TERMS>45 Net (terms date + 45)</POH_PAYMENT_TERMS>
<POH_SHIP_VIA>UPS</POH_SHIP_VIA>
<POH_FREIGHT_TERMS>Due</POH_FREIGHT_TERMS>
<POH_CURRENCY_CODE>USD</POH_CURRENCY_CODE>
<POH_CURRENCY_CONVERSION_RATE></POH_CURRENCY_CONVERSION_RATE>
<LIST_G_LINES>
<G_LINES>
<POL_LINE_NUM>1</POL_LINE_NUM>
<POL_VENDOR_PRODUCT_NUM></POL_VENDOR_PRODUCT_NUM>
<POL_ITEM_DESCRIPTION>PCMCIA II Card Holder</POL_ITEM_DESCRIPTION>
<POL_QUANTITY_TO_PRINT></POL_QUANTITY_TO_PRINT>
<POL_UNIT_OF_MEASURE>Each</POL_UNIT_OF_MEASURE>
<POL_PRICE_TO_PRINT>15</POL_PRICE_TO_PRINT>
<C_FLEX_ITEM>CM16374</C_FLEX_ITEM>
<C_FLEX_ITEM_DISP>CM16374</C_FLEX_ITEM_DISP>
<PLL_QUANTITY_ORDERED>7500</PLL_QUANTITY_ORDERED>
<C_AMOUNT_PLL>112500</C_AMOUNT_PLL>
<C_AMOUNT_PLL_DISP> 112,500.00 </C_AMOUNT_PLL_DISP>
</G_LINES>
</LIST_G_LINES>
<C_AMT_POL_RELEASE_TOTAL_ROUND>312420/<C_AMT_POL_RELEASE_TOTAL_ROUND>
</G_HEADERS>
</POXPRPOP2>

Adding Markup to the Template Layout

After you have converted your document to PDF, you define form fields that will display the data from the XML input file. These form fields are placeholders for the data.

The process of associating the XML data to the PDF template is the same as the process for the RTF template. See: Associating the XML Data to the Template Layout: Associating the XML data to the template layout.

When you draw the form fields in Adobe Acrobat, you are drawing them on top of the layout that you designed. There is not a relationship between the design elements on your template and the form fields. You therefore must place the fields exactly where you want the data to display on the template

Creating a Placeholder

You can define a placeholder as text, a check box, or a radio button, depending on how you want the data presented.

Note: If you are using Adobe Acrobat 5.0, the Form Tool is available from the standard toolbar. If you are using Adobe Acrobat 6.0 or later, display the Forms Toolbar from the Tools menu by selecting Tools > Advanced Editing > Forms > Show Forms Toolbar.

Naming the Placeholder

The name of the placeholder must match the XML source field name.

Creating a Text Placeholder

To create a text placeholder in your PDF document:

Acrobat 5.0 Users

  1. Select the Form Tool from the Acrobat toolbar.

  2. Draw a form field box in the position on the template where you want the field to display. Drawing the field opens the Field Properties dialog box.

  3. In the Name field of the Field Properties dialog box, enter a name for the field.

  4. Select Text from the Type drop down menu.

    You can use the Field Properties dialog box to set other attributes for the placeholder. For example, enforce maximum character size, set field data type, data type validation, visibility, and formatting.

  5. If the field is not placed exactly where desired, drag the field for exact placement.

Acrobat 6.0 (and later) Users

  1. Select the Text Field Tool from the Forms Toolbar.

  2. Draw a form field box in the position on the template where you want the field to display. Drawing the field opens the Text Field Properties dialog box.

  3. On the General tab, enter a name for the placeholder in the Name field.

    You can use the Text Field Properties dialog box to set other attributes for the placeholder. For example, enforce maximum character size, set field data type, data type validation, visibility, and formatting.

  4. If the field is not placed exactly where desired, drag the field for exact placement.

Supported Field Properties Options

BI Publisher supports the following options available from the Field Properties dialog box. For more information about these options, see the Adobe Acrobat documentation.

Creating a Check Box

A check box is used to present options from which more than one can be selected. Each check box represents a different data element. You define the value that will cause the check box to display as "checked."

For example, a form contains a check box listing of automobile options such as Power Steering, Power Windows, Sunroof, and Alloy Wheels. Each of these represents a different element from the XML file. If the XML file contains a value of "Y" for any of these fields, you want the check box to display as checked. All or none of these options may be selected.

To create a check box field:

Acrobat 5.0 Users

  1. Draw the form field.

  2. In the Field Properties dialog box, enter a Name for the field.

  3. Select Check Box from the Type drop down list.

  4. Select the Options tab.

  5. In the Export Value field enter the value that the XML data field should match to enable the "checked" state.

    For the example, enter "Y" for each check box field.

Acrobat 6.0 (and later) Users

  1. Select the Check Box Tool from the Forms Toolbar.

  2. Draw the check box field in the desired position.

  3. On the General tab of the Check Box Properties dialog box, enter a Name for the field.

  4. Select the Options tab.

  5. In the Export Value field enter the value that the XML data field should match to enable the "checked" state.

    For the example, enter "Y" for each check box field.

Creating a Radio Button Group

A radio button group is used to display options from which only one can be selected.

For example, your XML data file contains a field called <SHIPMENT_METHOD>. The possible values for this field are "Standard" or "Overnight". You represent this field in your form with two radio buttons, one labeled "Standard" and one labeled "Overnight". Define both radio button fields as placeholders for the <SHIPMENT_METHOD> data field. For one field, define the "on" state when the value is "Standard". For the other, define the "on" state when the value is "Overnight".

To create a radio button group:

Acrobat 5.0 Users

  1. Draw the form field.

  2. On the Field Properties dialog box, enter a Name for the field. Each radio button you define to represent this value can be named differently, but must be mapped to the same XML data field.

  3. Select Radio Button from the Type drop down list.

  4. Select the Options tab.

  5. In the Export Value field enter the value that the XML data field should match to enable the "on" state.

    For the example, enter "Standard" for the field labeled "Standard". Enter "Overnight" for the field labeled "Overnight".

Acrobat 6.0 (and later) Users

  1. Select the Radio Button Tool from the Forms Toolbar.

  2. Draw the form field in the position desired on the template.

  3. On the General tab of the Radio Button Properties dialog, enter a Name for the field. Each radio button you define to represent this value can be named differently, but must be mapped to the same XML data field.

  4. Select the Options tab.

  5. In the Export Value field enter the value that the XML data field should match to enable the "on" state.

    For the example, enter "Standard" for the field labeled "Standard". Enter "Overnight" for the field labeled "Overnight".

Defining Groups of Repeating Fields

In the PDF template, you explicitly define the area on the page that will contain the repeating fields. For example, on the purchase order template, the repeating fields should display in the block of space between the Item header row and the Total field.

To define the area to contain the group of repeating fields:

  1. Insert a form field at the beginning of the area that is to contain the group. (Acrobat 6.0 users select the Text Field Tool, then draw the form field.)

  2. In the Name field of the Field Properties window, enter any unique name you choose. This field is not mapped.

  3. Acrobat 5.0 users: Select Text from the Type drop down list.

  4. In the Short Description field (Acrobat 5.0) or the Tooltip field (Acrobat 6.0) of the Field Properties window, enter the following syntax:

    <?rep_field="BODY_START"?>

  5. Define the end of the group area by inserting a form field at the end of the area the that is to contain the group.

  6. In the Name field of the Field Properties window, enter any unique name you choose. This field is not mapped. Note that the name you assign to this field must be different from the name you assigned to the "body start" field.

  7. Acrobat 5.0 users: Select Text from the Type drop down list.

  8. In the Short Description field (Acrobat 5.0) or the Tooltip field (Acrobat 6.0) of the Field Properties window, enter the following syntax:

    <?rep_field="BODY_END"?>

To define a group of repeating fields:

  1. Insert a placeholder for the first element of the group.

    Note: The placement of this field in relationship to the BODY_START tag defines the distance between the repeating rows for each occurrence. See Placement of Repeating Fields.

  2. For each element in the group, enter the following syntax in the Short Description field (Acrobat 5.0) or the Tooltip field (Acrobat 6.0):

    <?rep_field="T1_Gn"?>

    where n is the row number of the item on the template.

    For example, the group in the sample report is laid out in three rows.

    The following graphic shows the entries for the Short Description/Tooltip field:

    the picture is described in the document text

  3. (Optional) Align your fields. To ensure proper alignment of a row of fields, it is recommended that you use Adobe Acrobat's alignment feature.

Adding Page Numbers

This section describes how to add the following page-features to your PDF template:

Adding Page Numbers

To add page numbers, define a field in the template where you want the page number to appear and enter an initial value in that field as follows:

  1. Decide the position on the template where you want the page number to be displayed.

  2. Create a placeholder field called @pagenum@ (see Creating a Text Placeholder).

  3. Enter a starting value for the page number in the Default field. If the XML data includes a value for this field, the start value assigned in the template will be overridden. If no start value is assigned, it will default to 1.

The figure below shows the Field Properties dialog for a page number field:

the picture is described in the document text

Adding Page Breaks

You can define a page break in your template to occur after a repeatable field. To insert a page break after the occurrence of a specific field, add the following to the syntax in the Short Description field of the Field Properties dialog box (use the Tooltip field for Acrobat 6.0):

page_break="yes"

For example:

<?rep_field="T1_G3", page_break="yes"?>

The following example demonstrates inserting a page break in a template. The XML sample contains salaries of employees by department:

<?xml version="1.0"?>
<! -  Generated by Oracle Reports version 6.0.8.22.0  - >
<ROOT>
  <LIST_G_DEPTNO>
    <G_DEPTNO>
      <DEPTNO>10</DEPTNO>
      <LIST_G_EMPNO>
        <G_EMPNO>
          <EMPNO>7782</EMPNO>
          <ENAME>CLARK</ENAME>
          <JOB>MANAGER</JOB>
          <SAL>2450</SAL>
        </G_EMPNO>
        <G_EMPNO>
          <EMPNO>7839</EMPNO>
          <ENAME>KING</ENAME>
          <JOB>PRESIDENT</JOB>
          <SAL>5000</SAL>
        </G_EMPNO>
        <G_EMPNO>
          <EMPNO>125</EMPNO>
          <ENAME>KANG</ENAME>
          <JOB>CLERK</JOB>
          <SAL>2000</SAL>
        </G_EMPNO>
        <G_EMPNO>
          <EMPNO>7934</EMPNO>
          <ENAME>MILLER</ENAME>
          <JOB>CLERK</JOB>
          <SAL>1300</SAL>
        </G_EMPNO>
        <G_EMPNO>
          <EMPNO>123</EMPNO>
          <ENAME>MARY</ENAME>
          <JOB>CLERK</JOB>
          <SAL>400</SAL>
        </G_EMPNO>
        <G_EMPNO>
          <EMPNO>124</EMPNO>
          <ENAME>TOM</ENAME>
          <JOB>CLERK</JOB>
          <SAL>3000</SAL>
        </G_EMPNO>
      </LIST_G_EMPNO>
      <SUMSALPERDEPTNO>9150</SUMSALPERDEPTNO>
    </G_DEPTNO>
    
    <G_DEPTNO>
      <DEPTNO>30</DEPTNO>
      <LIST_G_EMPNO>
        .
        .
        .   
        
      </LIST_G_EMPNO>
      <SUMSALPERDEPTNO>9400</SUMSALPERDEPTNO>
    </G_DEPTNO>
  </LIST_G_DEPTNO>
  <SUMSALPERREPORT>29425</SUMSALPERREPORT>
</ROOT>

We want to report the salary information for each employee by department as shown in the following template:

the picture is described in the document text

To insert a page break after each department, insert the page break syntax in the Short Description (or Tooltip field) for the SUMSALPERDEPTNO field as follows:

<?rep_field="T1_G3", page_break="yes"?>

The Field Properties dialog box for the field is shown in the following figure:

the picture is described in the document text

Note that in order for the break to occur, the field must be populated with data from the XML file.

The sample report with data is shown in the following figure:

the picture is described in the document text

the picture is described in the document text

The page breaks after each department.

Performing Calculations

Adobe Acrobat provides a calculation function in the Field Properties dialog box. To create a field to display a calculated total on your report:

  1. Create a text field to display the calculated total. Give the field any Name you choose.

  2. In the Field Properties dialog box, select the Format tab.

  3. Select Number from the Category list.

  4. Select the Calculate tab.

  5. Select the radio button next to "Value is the operation of the following fields:"

  6. Select sum from the drop down list.

  7. Select the Pick... button and select the fields that you want totaled.

Completed PDF Template Example

The following figure shows the completed PDF template:

the picture is described in the document text

Runtime Behavior

Placement of Repeating Fields

As already noted, the placement, spacing, and alignment of fields that you create on the template are independent of the underlying form layout. At runtime, BI Publisher places each repeating row of data according to calculations performed on the placement of the rows of fields that you created, as follows:

First occurrence:

The first row of repeating fields will display exactly where you have placed them on the template.

Second occurrence, single row:

To place the second occurrence of the group, BI Publisher calculates the distance between the BODY_START tag and the first field of the first occurrence. The first field of the second occurrence of the group will be placed this calculated distance below the first occurrence.

Second occurrence, multiple rows:

If the first group contains multiple rows, the second occurrence of the group will be placed the calculated distance below the last row of the first occurrence.

The distance between the rows within the group will be maintained as defined in the first occurrence.

Setting Fields as Updateable or Read Only

When you define a field in the template you have the option of selecting "Read Only" for the field, as shown in the following sample Text Field Properties dialog:

the picture is described in the document text

Regardless of what you choose at design time for the Read Only check box, the default behavior of the PDF processing engine is to set all fields to read-only for the output PDF. You can change this behavior using the following configuration properties in the BI Publisher Configuration File:

Note that in the first two options, you are setting a state for the field in the PDF output. The setting of individual fields can still be changed in the output using Adobe Acrobat Professional. Also note that because the fields are maintained, the data is still separate and can be extracted. In the third option, "remove-pdf-fields" the structure is flattened and no field/data separation is maintained.

To make all fields updateable:

Set the "all-field-readonly" property to "false". This sets the Read Only state to "false" for all fields regardless of the individual field settings at design time.

To make all fields read only:

This is the default behavior. No settings are required.

To maintain the Read Only check box selection for each field:

To maintain the setting of the Read Only check box on a field-by-field basis in the output PDF, set the property "all-fields-readonly-asis" to "true". This property will override the settings of "all-field-readonly".

To remove all fields from the output PDF:

Set the property "remove-pdf-fields" to "true".

Overflow Data

When multiple pages are required to accommodate the occurrences of repeating rows of data, each page will display identically except for the defined repeating area, which will display the continuation of the repeating data. For example, if the item rows of the purchase order extend past the area defined on the template, succeeding pages will display all data from the purchase order form with the continuation of the item rows.

Creating a Template from a Predefined PDF Form

There are many PDF forms available online that you may want to use as templates for your report data. For example, government forms that your company is required to submit. You can use these downloaded PDF files as your report templates, supplying the XML data at runtime to fill the report out.

Some of these forms already have form fields defined, some do not. If the form already has fields defined, you can either use BI Publisher's Mapping tool (see Adding a Predefined Form as a Template) or name your data fields to match the form field names (see Using a Predefined Form as a Template by Matching Form Fields). If the form fields are not already defined in the downloaded PDF, you must create them. See Adding Markup to the Template Layout for instructions on inserting the form field placeholders.

Using a Predefined PDF Form as a Template by Matching the Form Fields

  1. Download or import the PDF file to your local system.

  2. Open the file in Adobe Acrobat.

  3. Select the Text Field Tool (Acrobat 6.0 users) or the Form Tool (Acrobat 5.0 users). This will highlight text fields that have already been defined.

    The following figure shows a sample W-4 PDF form after selecting the Text Field Tool to highlight the text fields (in Acrobat 6.0).

    the picture is described in the document text

    To map the existing form fields to the data from your incoming XML file, you must rename the fields to match the element names in your XML file.

  4. Open the text form field Properties dialog by either double-clicking the field, or by selecting the field then selecting Properties from the right-mouse menu.

  5. In the Name field, enter the element name from your input XML file.

  6. Repeat for all fields that you want populated by your data file.