Home Page FO Designer user guide. XSL-FO tool for Oracle APEX and the Java[TM] platform
                                                  FO Designer guide
                                                • First steps
                                                • Introduction
                                                • The user interface
                                                • Working with the interface
                                                • Structure of the template
                                                • Executing the template to create PDF files
                                                • Learn by doing
                                                • The invoice IDOC example
                                                • The Group by example
                                                • The two columns example
                                                • Barcodes
                                                • Charts
                                                • The running totals example
                                                • Interactive forms
                                                • Flavours
                                                • The base template
                                                • Long texts and HTML fields
                                                • The memo field explained
                                                • Advanced functionalities
                                                • FOP Could Server
                                                • FAQS
                                                • Troubleshooting
                                                • Licenses
                                                • Structure of the template

                                                  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.


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

                                                  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.

                                                  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.