FO Designer user guide. XSL-FO tool for Oracle APEX and the Java[TM] platform

This section contains very valuable information to understand how the XML to PDF conversion takes place. First of all we will describe when and how areas are generated, then we will explain how the layout of the fields in the areas occur and last we will explain the meaning of the properties of each object involved in the template.

Page masters

In most cases your templates will have only one page master, that is, all pages look the same, they just contain different data. A page master describes the layout of a type of page and the areas it contains, including page header and page footer. What to do however if you want to have no page header and no page footer in the first page? in that case the first page would be using a different page master. This is for example the case when you want to have a cover page followed by the regular pages.

The departmentEmpCoverPage.xre contains such a template.

Each template can have up to 5 page masters that can be selected from the Outline view. Note the page master 1 must always be active but master 2 to 5 must be explicitly be activated, see "Master active" property in the screenshot below.

In this example the first master contains just the title of the report as a cover page, while the master 2 contains the layout of the pages that contains the employee data.

Note the XML schema and test data are common to all page masters. All page masters share the same source data (XML data), they just create different pages with different layouts.

If you run the provided template and generate the PDF, you will see the output is a PDF file with 3 pages, where the first page is the report cover page.

Properties of the page master

In the name section

    the name

    the activation flag

    the condition. This is an Xpath expresion to make masters optional

In the Dimensions section you can define a different page size and orientation for the master which overrides the report settings in the report properties.

Areas

The following screenshot shows a PDF file which can be split in 5 areas:

The header of the page (in this case it is empty).
The header of the document (in this case the header of a purchase order).
The header of the detail area, it contain the labels of the columns in the detail area.
The detail area, in this case 2 repetitions (lines) of the detail area.
The footer of the document (commonly used for showing totals).
Additionally there is a page footer (not shown in this screenshot) which can contain, for example, the page number.

In the same way a normal business document contains this kind of areas the template you create in the FO designer contains also the following types of area:

One template header and footer. Each PDF file will normally contain only one document header and one document footer, however it is possible to have several headers in one PDF file, for example if you are printing several invoices in one PDF file.
One page header and footer. These areas are printer in each page
detail areas (optional).

Area can have subareas. Each time an area is generated (added to the PDF file), the dependent (sub)areas will be generated. The template Header is the first area generated , afterwards all first level areas (those that are right below the master in the outline view)
the XML node property specifies when the area must be generated. The XML node property contains an XPath expression which points to an element in the input XML file. The area will be generated if the element exists in the XML file, if several elements exist, several repetitions of the areas will be generated. If the XML Node property is left empty, the area will be generated only once.

Detail areas may have a detail area header (as in area number 3 in the screenshot above), this header area however can be removed from the PDF output (see Visible checkbox below)

The delivery includes a file called order.xre which is the template used to create the above PDF file. This template uses a XML purchase order (using the xcbl schema) as input file. The following screenshot provides and overview of the schema:

The root element is called Order, under this root element there is a OrderHeader element, a OrderDetail element and a OrderSummary element.

In the following screenshot you see an overview of the template file.

It contains the 6 areas we mentioned above:

The document header (contains the purchase order header) and footer (contains the total values)
The page header (is empty) and footer (contains the page number)
The detail area (for the articles) and the columns header of the detail area.

When the template is executed:

The page header and footer will be added to each page
The Header area will be generated. If the XML node property is empty, the area will be generated only once, if it contains a XPath expression as in this case, it will be generated as often as elements are return by the XPath expression. In the example the header will be created once for each /Order element in the input XML file.
For each instance of the header , the dependent areas will be generated. These will be all first level areas (the ones right below the master in the outline view). In this case the Detail area.

so we know the detail area will be generated after the header area , but how often? this depends on the XML node property (see arrow 1 in the screenshot). In this example we will create one repetition (line of the detail area) for each ItemDetail node in the input XML file. In other words, we will create one detail line for each item in the purchase order.

Last as you see in the Visible property in the „Detail Columns header“ this header which will be generated before the detail area and contain the labels of the columns.

In this example each XML input file can contain only 1 purchase order, however let's suppose it does contain two /Order elements. In this case we would get two instances of the header area and of course we want the items belonging to the first order to be selected when the first header has been generated and the items belonging to the second order to be selected after the second header has been generated. That is why the XML node type property of the detail area has been set to relative.

That means, select only the ItemDetail elements which belong to the /Order element being generated. If you for example set that value to absolute, you would be selecting all items in the XML file, not only those belonging to the current order.

The same logic applies to the individual fields. Each field has a XPath property and XPath type property:

In the screenshot above you can see the value for the description field will be selected from the ItemDescription element which is located somewhere below the ItemDetail an element (which is the XML Node of the area). Since we want to select the item description of the current ItemDetail node, we set the XPath type to relative.

How to analyze the report execution

The magnifying glass in the toolbar will trigger the creation of the PDF file and will trace the execution of the XSLT engine.

Let‘s run this feature for the departmentEmployees.xre report. This report will create a new report for each department (note the /departments/department node in the Header area), and will list all the employees of the department (/departments/department/person node selection).

The input test XML file will be:

If we click on the PDF button the result will be as below since the test XML file contains 2 departments with 4 and 2 employees each.

Click now on the Analyze button, a new window will open.

First the „Area Header“ will be generated (step 1), but only if there are „departments“ in the input XML file (step 2, runs a test on XPath departments/department). Since step 2 determines there are departments, it will select them (step 3), which returns 2 departments. This means for each one of these departments a new report header area will be generated.

Next you see the 2 constant labels „lblEmployees“ and „lblDepartment“ (the constant value itself is not visible in the trace) and the one variable field „fldDepartment“ begin generated. In step 1 the executed XPath expression for the variable field is visible, in step 2 the result of the XPath will be displayed (in this case the value „R & D“)

the result of the trace above is:

Now the detail area will be generated. That is, the list of employees belonging to the first department. As in the case of the report header, there is first a test to check whether the area will be generated at all. In this case, the detail area will be generated 4 times.

For each person (detail area), a comment „repetition of Detail“ can be found in the trace.

Further down in the trace the second repetition of the Header (second department node) can be found. The second department name „Sales“ has been generated, a new detail area will be created, this time with 2 employees.

XSL / FO Troubleshooting

In case you get an XSL or FO error while running the report you can use this the trace to find the location. For example , when there is an execution error the trace shows the link below

The link will open the location of the XSL or FO trace where the error happened (red text below). This make is easy to locate and fix errors because of the comments located nearby

Background colors and images

Areas can have background color or background images, the available options are:

Set the opaque property to Yes (check) and select a background color
or set the opaque property to No (uncheck) and set a background image. The background image can be align horizontally and vertically by using the Background align properties. Select the image in the local system (back Image field), for later execution on the server, fill in the „Image dir. Server“.

You can use the „show b. Image“ flag for showing the image in the designer, if you remove this flag the image will still be created in the output but not shown in the designer
The embed image will include the image in the xslfo file as base64 resource so no image file will be required at runtime, Finally the scale flag will scale the image in a uniform way (i.e. without changing the aspect ratio)

The background image example

The BackgroundAlign.xre example shows how to use a background image and align some data fields to the background contents.

In order to align the field to the background the following flag must be set:

This makes sure the designer does not create a table like layout for the area. Instead only one table cell will be created and the fields will be positioned at the same absolute position as in the designer.

Note this means fields may not grow since they could overlap other fields placed at fixed positions.

The embed setting will include the image within the xslfo file so there is no need of having the image in a separate image file.

Finally the scale image flag will scale the image to fill the area. It is however recommended to provide at image with the correct size since scaling can distort the image. The image must be approximately 37,5 per CM (or 96 pixels per inch)