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.
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
The departmentEmpCoverPage.xrecontains 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
The following screenshot shows a PDF file which can be split in 5
The header of the page (in this case it is empty).
The header of the document (in this case the header of a purchase
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
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
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
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 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.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 schema:
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 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
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 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 nodeproperty
(see arrow 1 in the screenshot). In this example we will create one
repetition (line of the detail area) for each ItemDetail node
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 /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 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
Background colors and images
Areas can have background color or background images, the available
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 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
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)
The background area
The background area contains objects that will be placed on each page
at a fixed location. The background area is located as last area in the
Master object in the outline view:
as with header areas you can remove the area from the output using the
visibility flag in the area properties view.
If you use the background area, make sure regular areas have the opaque
property set to false otherwise they will be overlap the
You can see an example of a background area in tasks_background.xre.
Columns and rows markers
FO designer will always internally create a XSL-FO table
(similar to a HTML table) and place each field or image in one cell in
the table. In most cases this is done automatically however there are
some situations where you explicitly have to define the columns and rows
of the area as explained below.
You use the Row and Column marker object of the palette and place them
in the position where you want to have the row and column separation of
the generated table