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 file.
One page header and footer. These areas are printer in
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 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
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 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
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 type property 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 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 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.
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 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
The cases where you need to define the columns and rows separator
if you have an object that expands several rows (for example an
if you want to paint a frame or line around the column, row or cell
( see the frame properties in the area's properties)
in case the automatic layout of fields does not produce the expected
output, you may need to define the columns and rows yourself to have a
better control how the objects will be aligned.
The following example illustrates case 1. The following screenshot
shows a purchase order template with an image on the right side
the output PDF is:
the problem here is the image and the "Purchase order" text are placed
on the top which is correct but all other fields and moved further down
in the page. If you however define the rows and columns yourself like
the output will look correct because you tell the designer the area
has 2 rows, in the first one you have the "Purchase order" text and
the image, furthermore the image occupies both rows.
Note the rules for placing the column and row separators are:
1.Objects can span one or more rows, if they span more than 1
row, no other objects must be placed in the cells below it (as in
the logo image object above)
2.Objects can span one or more columns. See for example, Name,
address and City fields above, they occupy
columns 1 and 2.
3.You can have several objects in one cell but they have to be
place at different heights (top to bottom placement). Placing
several objects in the same cell, from left to right will not
produce the desired output.
The following example illustrates case 3. If you remove the columns
separator between the Number:
Number field like this:
You have now 2 objects at the same height and the output will be
incorrect (see below) because the designer is unable to put 2 object
at the same Y position unless there is a column separator:
Note: if you do not create any column, the designer will
automatically (internally) do it for you, however if you define at
least one column separator, the automatic mode will be disabled and in
this case you have to place all columns separators (as shown in this
Drawing lines with columns and
Columns and row marker can be used for drawing vertical and horizontal
lines. By clicking on the marker icon, the properties will be displayed.
If the property yes, the line will be painted.