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

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:

• 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.

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.

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 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

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:

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.

• Date format: format of the dates in the input XML file. The default one is yyyyMMdd"T"hh:mm:ss. This property is important if the template has to reformat the date fields (see format property in the field object). This is the input date format in the XML file.
• Orientation: horizontal for landscape and vertical for Portrait.
• Size: page size. it can be custom or predefined.
• Margins: define the margins of the page.
• Name: name of the template, used for information purposes only.
• Base template file: this is a template report file which contains 3 areas (page header, page footer and background area). It can be used to have a common page header for all reports in a company (see the Base Template example  further down in this document)
• Documentation: free text for documentation purposes

Properties of the areas

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

• XML Node: if this element is empty, the area will be generated only once. If this area however contains a XPath expression, the area will be generated as many times as elements returned by the XPath.
• XML Node Type: If absolute the XPath will be evaluated as you see it in the designer. If relative, the XPath will be relative to the current element (XML Node property) in the super area.
• XML Sort: enter an XPath if you want to sort the elements returned by the XML Node property. The XML Sort property is a XPath that returns a list of elements used as key for sorting. For example, you could set the XML Node to be the items in the purchase order as in our example /Order/OrderDetail/ListOfItemDetail/ItemDetail. The you could sort using the article number /Order/OrderDetail/ListOfItemDetail/ItemDetail/BaseItemDetail/ItemIdentifiers/PartNumbers/BuyerPartNumber/PartNum/PartID.
• XML Sort type: whether the sorting elements are numeric of alphanumeric values.
• XML Sort order: ascending or descending.
• XML Group by: used for grouping values (see additional section of this topic)
• Local group: select this if the grouping shall not be propagated to the subareas.
  
• Set row height: this setting makes sure the area will have the same height as you define in the designer. If you remove this setting the area will shink when there is no data in it. In some cases if you have conditional fields (using flavours) this can be useful to avoid empty spaces.
  
• Background: background color of the area
• Background image: select background image for the area.
• Back H align: horizontal alignment of the background image.
• Back V align: vertical alignment of the background image.
• Image dir server:  directory where the file will be found at runtime.
• Show b image: show or hide image in the designer.
• Scale b image: Scale the image to fill the area , the aspect ratio will not change.
• Embedd b image: embed the image in the XSLFO as Base64 encoded resource.
• Frame: select a value different from NONE to enable the area's frame. Possible values are: o AREA BORDER: paint only the border of the area
• ONLY ROWS: paint only horizontal lines to separate area repetitions and rows within the area.
• ONLY COLUMNS: paint only vertical lines to separate columns in the area (see column markers).
• GRID: all above will be painted.
• Frame color: select the color with the color .
• Frame style: select one of the styles
• Frame width: select THIN, MEDIUM or THICK.
• New page (page break): if true the area will be generated in a new page.
• Keep together (in detail areas only): if true the area will be printed in the next page when not all fields fit in the current page.
• Fixed fields: This flag allows placing the fields at a fixed position in the area. This means fields are not allowed (shall not) to expand since they have fixed positions and would overlap the fields below or to the right. Also this setting disables the creation automatic of columns and rows, furthermore columns and row markers you place in the area will be ignored. The main purpose of this flag is to align the fields to a fixed background image (for predefined form images).  
• Rows per page: if you set this value to a number higher than 0, a new page after X repetitions of the area (being X the number you enter).

Properties of a text field

Click on the object to display its properties.

• constant: set it to true if this is a constant field (ie. a label). Note if a field has been declared as constant (as a label), the border will be black instead of blue, in this way you can easily recognize which fields contain variable data and which field are labels.
• value: constant value (instead of using a XPath). It will be used if the constant property is set to true or the XPath property is empty.
• XPath: path to the source XML element of this field. It can be any valid XPath expression, that is, it can contain conditions and functions. The employee tutorial contains an example how to use functions and the invoice IDOC example uses the condition technik extensively.
• XPath type: If absolute the XPath will be evaluated as you see it in the designer. If relative, the XPath will be relative to the current element (XML Node property) of the area.
• Align: text alignment
• Background: select background color of the field.
• Background opaque: set it to true to activate the background color.
• Border: set it to true to activate the border of the field
• Border Color, Style and width: properties of the border.
• FO attributes: any xsl-fo attributes to add to the field. Note this might lead to errors if you use attributes not compatible with the one generated by the designer.
• Font: currently only the built-in fonts are supported (SansSerif, Courier, Times Roman and Symbol).
• Font color: self explanatory.
• Format: output format for dates and numbers. For numbers the format is:
• # denotes an optional digit.
• 0 denotes a digit.
• . decimal point.
• , is the group separator for thousands.
• ; Pattern separator. The first pattern will be used for positive numbers and the
• second for negative numbers.
• % percentage sign

            For dates the format is:

• y: year
• M: month
• day of month
• H: hour (0-23)
• m: minute
• s: second

            further information can be found in the Java documentation of the SimpleDateFormat class.

• Rotation: use this field to rotate the text
• Preserve LF: set it to true to keep all spaces in the value..

Properties of a combo box

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

• Key List: a list or key/value pair. The element returned by the XPath will be used as key to find the value in the list. This value will be the output in the PDF File.

• Memo text: contains the long styled text.
• Variables:  Xpath for the placeholders in the memo text. The variable placeholder texts are $1 to $5 . See HelloWorldMemo example in this document.

Properties of a picture

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

• Image: path to the image. There are 3 types of images (Constant property):
• CONSTANT FILE. These are fixed image files which can be loaded into the report.They do not have to be available at runtime. See for example order.xre.
• DYNAMIC FILE: these are images which are located on the file system but the name is calculated at runtime using a XPath expression. See example personCard.xre. We recommend placing images below the working directory. That will be either in the FODesigner directory or in the server, below the J4LFOPServer directory.
• FROM XML. These are images located inside the source XML file as a base64 image, they are also referenced with an XPath expression. See for example "order_logo.xml" and test file "OrderSample-ABC-Image.xml".
• Load image in FO file (for constant images): select to load a base64 representation of the image, otherwise the image will be read from the file system at runtime.
• Local image URL (for constant images): if the the above flag is not selected this will be the location of the image in your computer at design time.
• Server image URL (for constant images): if the the above flag is not selected this will be the location of the image in the server at runtime.
• Scale to Fit: scale the image to fit the size of the picture object in the template.
• Scaling: the default behaviour is to scale the image using "uniform" scaling which makes sure the aspect ratio of the image does not change. Use "non-uniform" if you want to scale the image without aspect ratio considerations.
• Constant: see Image property.
• Type: set automatically when the image is loaded.

Properties of a line

• Line Width: width of the line.
• Style: type of line (dots, dashed ...).
• Line length: (default 100%). You can define the length in % or in cm.
• Orientation: vertical or horizontal.

Properties of a www links

• Link label: label displayed in the PDF file. If empty, the www address will be shown.
• Value: www value, either as a constant value or as a XPath expression..

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:

• Code: use the editor to add code. Note you have to use the prefix “fo:” for fo elements and the prefix “xsl:” for xls elements. 
• Location: of the code. The code can be handled as attributes of the current cell/row/table or as standalone code before the area or inside the current cell.

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