4. Structure of the template

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

    New page seq. for header. If set it will create a new page-sequence element in the XSL-FO for each element in the Report‘s header node. This results on the page number being reset to 1. This is useful to create batch of documents within one PDF file, where each document has a page number starting with 1.


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:

  1. The header of the page (in this case it is empty).
  2. The header of the document (in this case the header of a purchase order).
  3. The header of the detail area, it contain the labels of the columns in the detail area.
  4. The detail area, in this case 2 repetitions (lines) of the detail area.
  5. The footer of the document (commonly used for showing totals).
  6. 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:

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:

When the template is executed:

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.



the result of the trace above is:





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:

  1. Set the opaque property to Yes (check) and select a background color
  2. 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
  3. 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)



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 background area.

You can see an example of a background area in tasks_background.xre.

Attachment to the PDF file


It is possible to add the original input XML file to the PDF file as an attachment. In the report‘s properties that are two entries:
    • XML attachment. Set this flag to add the input XML to the PDF
    • Attach. Name: enter here a Xpath or constant value. If empty the attachment name will be generated at runtime.



After setting the properties as above the xml file will be available as an attachment





Report's metadata


The metadata tab in the properties can be used to set the PDF metadata information as below



The result will be visible in the File – properties menu of the PDF viewer




The two PDF modes properties can be set to make sure the PDF is complaint with the following standards:
    • PDF/A-1b : more information at https://en.wikipedia.org/wiki/PDF/A
    • PDF/X-3:2003 : more information at https://en.wikipedia.org/wiki/PDF/X

Decimal numbers formatting


In the report‘s properties , Numbers tab, the format of the decimal numbers can be defined. Set the flag at the top if you want to override your platform‘s default settings.




Beware that the entered values in „decimal separator“ and „group separatorneed to match the ones used in the format setting of the fields.




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 yourself are:

  1. if you have an object that expands several rows (for example an image)
  2. if you want to paint a frame or line around the column, row or cell ( see the frame properties in the area's properties)
  3. 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 this:

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 last example).

Drawing lines with columns and rows markers

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.



Conditional data using row conditions

You can have optional data in your area by using the condition Xpath in the Row Marker properties. In the example below, the row marker containing the ProductDesc field has a condition to create the row only if the ProductDesc exists. For area repetitions with no ProductDesc element the row will not be created and therefore there will be no empty space for the missing data.




Properties of the objects

Some properties of the object, like the position (X and Y) and size are self-explanatory, therefore they will not be listed here.

Properties of the template

Select the report object in the outline view to display the properties of the template.

Properties of the areas

Click on the area ruler or on the area in the outline view to display the area‘s properties:

Properties of a text field

Click on the object to display its properties.

            For dates the format is:             further information can be found in the Java documentation of the SimpleDateFormat class.

Properties of a combo box

Click on the object to display its properties (see also properties of a text field).

Properties of a memo field



Properties of a picture

Click on the object to display its properties (see also properties of a text field).

Properties of a line

Properties of a www links

Properties of a free code objects

The free code objects are required when you need to add code to the xsl-fo output. This should be done only if you are familiar with the xsl-fo language. If the code is not correct the PDF generation will fail.

The 2 main properties are:

Example 1

This simple code will add the work “Hello” to the output


In the code tab you will see the code has been added to the output


And in the preview tab you can see the generated PDF :

Example 2

This code shows how to store the value of an input field into a variable. The variable will be set before the area is created in this way it can then be used by all sub areas.

Select the property location „table before"

We can then place a text field in another area to read and show the variable (note you use the sign $ following by the variable name):


The output shows then the variable value:



Properties of a table frame


The table frame object creates a complex frame (table like) around existing fields.Note this object is only a decoration object, it does not contain any fields or logic.

the properties are:


Properties of the cell


Table frame object are always added to the background of existing objects. You work with table frames in this way:



the example order_tableframe.xre produces the output below, for this the properties of the table and cells area: