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
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
The departmentEmpCoverPage.xrecontains such a
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 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.
The following screenshot shows a PDF file which can be split in
The header of the page (in this case it is empty).
The header of the document (in this case the header of a
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
The footer of the document (commonly used for showing
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 nodeproperty 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
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
The delivery includes a file called order.xrewhich
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 root element is called Order, under this root
element there is a OrderHeaderelement, aOrderDetail element and a OrderSummaryelement.
In the following screenshot you see an overview of the template
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
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 nodeproperty 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
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
so we know the detail area will be generated after the header
area , but how often? this depends on the XML nodeproperty (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
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 /Orderelements. 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 typeproperty of the detail
area has been set to relative.
That means, select only theItemDetail 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
aXPath property and XPath typeproperty:
In the screenshot above you can see the value for the
description field will be selected from theItemDescriptionelement which is located somewhere below theItemDetailan element (which is the XML Node of the
area). Since we want to select the item description of the
current ItemDetailnode, we set the XPath
type to relative.
How to analyze the report
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
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
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 toYes (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
The BackgroundAlign.xre example shows how to use a
background image and align some data fields to the background
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)