2. The page layout


In the previous example some elements have already been introduced which are needed for the page layout. Here, the concept of page layout and page sequence shall be examined in detail. The possible elements of a page layout are demonstrated in the following graphic and explained in the next chapters:

Element structure of a page

Element structure of a page

2.1. The page layout

You can see the layout of the pages in the following graphics:

Page layout

Page layout

("Druckbereich" means print area.)

For the definition of a page in XSL-FO the following details are required:

  • page width (page-width)

  • page height (page-height)

  • margins (optional), divided into four regions:

    • top (margin-top)

    • bottom (margin-bottom)

    • left (margin-left)

    • right (margin-right)

This information must be provided in the fo:simple-page-master element with the help of attributes.

This information could be as follows:

<fo:simple-page-master master-name="HelloWorld"

Other relevant attributes of the <fo:simple-page-master> element for the orientation of the text are:

  • reference-orientation, writing-mode


2.2. The print areas

Print areas are used in order to subdivide the page. As the graphic shows, five different regions can be distinguished. Special attention should be paid to the fact that the positioning of these regions is bound to our usual writing direction (from the left to the right and from the top to the bottom).


Print areas

  • head region (<fo:region-before>)

  • foot region (<fo:region-after>)

  • left region (<fo:region-start>)

  • right region (<fo:region-end>)

  • body region (<fo:region-body>)

Each of these regions is a child element of <fo:simple-page-master> which specifies the characteristics of these regions.

Here is a small example:

<fo:simple-page-master master-name="HelloWorld">
   <fo:region-before extent="20mm"/>                         (1)
   <fo:region-after extent="20mm"/>                          (1)
   <fo:region-body margin-top="10mm" margin-bottom="10mm"/>  (2)

(1) The extent attribute used in this example indicates the extension of this region, which means that the height is indicated in the case of the header and footer.

(2) The body is an exception because its extension is not indicated. It is rather the region which is left over in the middle of a page after all of the margins and regions have been defined. For the page layout on the whole and in many block elements there is a possibility to reserve borders or marginal areas. In this example a 10 mm high margin is specified at the bottom and at the top body region. Togheter with the head and foot region, this means that the content of the body region begins and ends at a 30 mm distance from the top and bottom margin. But the content borders directly on the margins because the start and end regions are not specified.

Further crucial attributes for the identification, borders and margins, fillings and backgrounds of the region elements are:

  • region-name

  • display-align

  • column-count, column-gap

  • reference-orientation, writing-mode

  • clip

  • overflow


2.3. The writing direction

The writing direction for the text is – as known – in many languages different compared to the European languages. XSL-FO supports the standard writing directions for all world languages. The writing direction can be determined with the writing-mode attribute for entire pages in the <fo:simple-page-master> element or in text blocks or even in the inline text. Thus, it is for example possible to create an Arabic-German dictionary where the writing direction in a line varies. The writing-mode attribute has three possible values: lr-tb (leftright-topbottom), rl-tb (rightleft-topbottom) and tb-rl (topbottom-rightleft). The first combination of letters specifies the writing direction in the lines, the second specifies the direction of the stringing together for the text blocks.

Writing direction

Writing direction

As you can see in the graphic, the writing direction also determines the positioning of the page regions.

The writing direction can also be controlled by the orientation attribute reference-orientation.


2.4. The orientation

With the help of the reference-orientation attribute the orientation can be changed, for example in order to rotate texts. It may have seven values: 0, 90, 180, 270, -90, -180, -270. The value 0 is the default value. The values are grade indications which allow the rotation of text blocks or lines in 90° angles. As a result the regions of a text block (e.g. top or left margin) also rotate.



For clarification of the functionality a small example:

 <fo:block-container reference-orientation="90">    (1)                        
    <fo:block font-size="8pt">Example for the text orientation.</fo:block>

(1) The alteration of the orientation is only valid in the container element fo:block-container, but not, for example, in the simple blocks (fo:block). Here, the reference-orientation attribute effects a 90° rotation of the text.


2.5. Units of measurement

The units of measurement supported by XSL-FO are:

Unit of measurement Explanation
cm Centimetre
mm Millimetre
in Inch (1 in = 2,54 cm)
pt DTP points (1 pt = 1/72 in = 0,353 mm); derivate slightly from the Didot points (= 0,376 mm)
pc Picas (1 pc = 12 pt)
px Pixel
em Unit dependent on the font and the font size (width of a M); in practice 1 em corresponds to the font height

The Antenna House XSL Formatter supports all of these units including the first decimal place.


2.6. Defining templates for page sequences 

The <fo:page-sequence-master> element is, apart from the already introduced <fo:simple-page-master> element, the second child element of the <fo:layout-master-set> element. The <fo:page-sequence-master> element determines in which order the page layout (default pages) or sequences of page layouts are inserted into the document. The page sequences (<fo:page-sequence-master>) are a bundling of individual pages or of entire sequences. The <fo:page-sequence> element determines in which order they will appear in the document.

In this book for example, as in many other books, left and right pages have to be treated differently, the preface has to be provided with a page numbering of Roman numerals and the table of contents has to be generated in a specific layout.

The <fo:page-sequence-master> element only contains one attribute which determines the reference name (master-name). The page sequences are defined by the included elements <fo:repeatable-page-master-reference><fo:repeatable-page-master-alternatives>, <fo:conditional-page-master-reference> and <fo:single-page-master-reference>.

As an example the page sequences for the main part of this book:

<fo:page-sequence-master master-name="Content-Pages">                         (1)
   <fo:repeatable-page-master-alternatives>                                   (2)
      <fo:conditional-page-master-reference                                   (3)
      page-position="first" odd-or-even="odd"/>
      <fo:conditional-page-master-reference                                   (4)
      page-position="rest" odd-or-even="even"/>
      <fo:conditional-page-master-reference                                   (4) 
      page-position="rest" odd-or-even="odd"/>
      <fo:conditional-page-master-reference                                   (5)
      page-position="last" odd-or-even="even" blank-or-not-blank="blank"/>
      <fo:conditional-page-master-reference                                   (6)
      page-position="last" odd-or-even="even"/>
      <fo:conditional-page-master-reference                                   (6)
      page-position="last" odd-or-even="odd"/>
   <fo:single-page-master-reference master-reference="PageMaster.Reference"/> (7)

(1) In this example as well as in the <fo:simple-page-master> elements, the master-name attribute determines the names of the page sequence which is defined in the <fo:page-sequence-master> element.

(2) The <fo:repeatable-page-master-alternatives> element makes it possible to repeat defined pages in <fo:simple-page-master> elements or determined page sequences in <fo:page-sequence-master> elements or to let them run under certain conditions. The maximum-repeat attribute is used in order to determine the number of repetitions.

(3) <fo:conditional-page-master-reference> indicates an alternative. The master-reference attribute references the page definition or page sequence which shall be used when the first page is concerned (page-position="first"). Moreover, it is defined that the first page shall always be a page with an odd page number (odd-or-even="odd"). If the content of the previous pages ends in an odd-numbered page, a blank page will be inserted auotmatically, so that the new page sequence can start with an odd-numbered page. In this book this applies to all chapters of the first level. All of them start on the right side.

(4) At this point the layout of an even-numbered or an odd-numbered page is determined for the rest of the pages (page-position="rest").

(5) Here, the layout of an even-numbered (left) last and blank page is determined (page-position="last" odd-or-even="even"blank-or-not-blank="blank").

(6) If the last page is not blank, the here determined page definitions will apply.

(7) The <fo:single-page-master-reference> element determines a page or page sequence which is used in any case at this position (in this example after all the other page sequences).

The following graphic shows the flow of the pages and page sequences according to the definition above:

Page sequences

Page sequences

The <fo:single-page-master-reference> element only has one attribute (master-reference).

<fo:conditional-page-master-reference> may contain the following attributes:

  • master-reference

  • page-position

  • odd-or-even

  • blank-or-not-blank.

<fo:repeatable-page-master-alternatives> can only be specified with the maximum-repeat attribute.

2.7. Colour profiles

The optional <fo:declarations> element may contain one or several <fo:color-profile> child elements which define and reference colour profiles. If you want to apply the colour profile RGB (Red – Green – Blue) which is commonly used in the web, you do not have to define it because RGB is valid without any declaration. However, the RGB profile is not very helpful when you want to use a more multifaceted colour print. When choosing another profile, for example CMYK, the definition would be like this:

   <fo:color-profile src="..." color-profile-name="CMYK"/>

In the src attribute reference has to be made to the external stored colour profile data in place of the "...".


2.8. Determination of page sequences

As shown above, the <fo:page-sequence-master> element is responsible for the bundling of the defaults for pages and page sequences. The <fo:page-sequence> element decides how these sequences are called up in the set of the XML instance and determines the order of several page sequences in which these are to be processed.

A further task of the <fo:page-sequence> element is to assign the contents to the regions defined in the <fo:simple-page-master> element. Within the <fo:page-sequence> element, the regions which contain the real content (head region, foot region, start region and end region) are filled with their static contents. Furthermore, it is specified for the content region which contents of the XML instance in this sequence shall be imported for processing.

The following example shows non-executable, highly simplified excerpts from the stylesheet on which the layout of this book is based. Here, only the basic connections of the elements <fo:layout-master-set>, <fo:simple-page-master>, <fo:page-sequence-master> and <fo:page-sequence> shall be presented.

    <fo:layout-master-set>                                                        (1)
        <fo:simple-page-master margin="{$PageMargins-Content-right}" 
             master-name="PageMaster.Content-right">                              (2)          
            <fo:region-body margin="{$Body-Margins-Content-right}"/>              (3)
            <fo:region-before region-name="Content-right-before" extent="15mm"/>  (4)
            <fo:region-after region-name="Content-right-after"/>                  (5)
        <fo:page-sequence-master master-name="Content-Pages">                     (6)
            <fo:repeatable-page-master-alternatives>                              (6)      
                <fo:conditional-page-master-reference                             (6)
                    page-position="first" odd-or-even="odd"/>                         
                    page-position="rest" odd-or-even="even"/>                         
                <fo:conditional-page-master-reference                             (6)
                    page-position="rest" odd-or-even="odd"/>                         
                <fo:conditional-page-master-reference                             (6)
                    page-position="last" odd-or-even="even"/>
                <fo:conditional-page-master-reference                             (6)
                    page-position="last" odd-or-even="odd"/>
    <fo:page-sequence master-reference="TableOfContents" force-page-count="even"> (7)
    <fo:page-sequence master-reference="Content-Pages" force-page-count="even">   (8)
        <fo:static-content flow-name="Content-right-before-start">                         
            <fo:block>First page header</fo:block>                         
        <fo:static-content flow-name="Content-right-before">                      (4)                 
            <fo:block>Right page header</fo:block>
        <fo:static-content flow-name="Content-left-before">                         
            <fo:block>Left page header</fo:block>
        <fo:static-content flow-name="Content-right-after">                       (5)
            <fo:block>Right page footer</fo:block>
        <fo:static-content flow-name="Content-left-after">                         
            <fo:block>Left page footer</fo:block>
        <fo:flow flow-name="xsl-region-body">                                     (3)
                <xsl:apply-templates/>                                            (9)

(1) In the <fo:layout-master-set> element all defaults for individual pages and page sequences are defined.

(2) The <fo:simple-page-master> element defines the size of the page, the borders and regions. In this case the default page has the name PageMaster.Content-right. In the example this name is taken up again in the <fo:page-sequence-master> element in order to integrate this page in a page sequence. In fact, in this example several other <fo:simple-page-master> elements were omitted in order to retain overview.

(3) The <fo:region-body> region has no region-name because it holds the fixed, preset name xsl-region-body.

(4) In this example the <fo:region-before> region, meaning the header of the page, has the name Content-right-before. It has to be called up in the <fo:page-sequence> element to assign content to this region. The assignment is done in the header by the <fo:static-content> element which inserts fixed contents into this region. On the one hand, the fixed content can be absolutely static (for example in an unalterable title in all pages of the given page sequence). On the other hand, the content can be generated, as in the case of the consecutive page numbering or also of a running head (for example the repetition of the current section title in the header).

(5) For the footer the same applies as for the header of a page.

(6) In the <fo:page-sequence-master> element the page definitions are now collected in page sequences under the name Content-Pages. This name is called up in the <fo:page-sequence> element, so that the formatter can execute the page sequences being defined in the <fo:page-sequence-master> element and fill them with content.

(7) With the <fo:page-sequence> element at least one page sequence, and when stringing together several of these elements a corresponding number of page sequences, is generated in the stylesheet in accordance to its sequential arrangement. The content designated in the stylesheet (in this example replaced by ...) is integrated in the sequence of the pages. This example has two <fo:page-sequence> elements. The first one refers to a <fo:page-sequence-master> or a <fo:simple-page-master> with the name TableOfContents, the second one refers to <fo:page-sequence-master> with the name Content-Pages.

(8) Here, the <fo:page-sequence> element contains several <fo:static-content> elements which describe the various headers and footers of the left and right pages with a short text. This text would appear in the different regions of the pages. The <fo:flow> element determines where the running text shall be inserted. Each <fo:page-sequence> element may only contain one <fo:flow> element. This element has to be put after all <fo:static-content> elements within <fo:page-sequence>.

(9) With the <xsl:apply-templates/> element the whole content of the instance is inserted at this position because the given stylesheet part within the template is placed for the top element (the root element) of the XML instance to be set.

<fo:page-sequence> may contain the following attributes:

  • master-name refers to the name of the page sequence

  • id defines an ID for the page sequence

  • language indicates the language of the content of the page sequence

  • country specifies the country in which language the content is written

  • initial-page-number indicates the initial value for the page numbering

  • force-page-count determines whether the page sequence ends or begins with an even-numbered or an odd-numbered page

  • format determines the page numbering format

  • grouping-separator, grouping-size allow further determinations for the type and the format of the numbering

  • letter-value for the formatting of the page numbers when alphanumeric counting is used.


2.9. Text flows and static contents

Within the <fo:flow> element the contents flow and are broken up into pages, if the volume exceeds the capacity of a page. The content of this element determines the line and page break and thus also the number of generated pages.

The <fo:static-content> element determines the static contents of page regions outside the region which takes the running content in. The content of these regions is not involved in page and line breaks. For example, if the content of a <fo:static-content> is too big for one page, the formatter won' t generate a page break but either stop the formatting or output a warning which shows the overflow in the given region.

Both elements <fo:flow> and <fo:static-content> only have one attribute, flow-name. The attribute value refers to the region-name attribute with the same attribute value in a <fo:simple-page-master> element.

Within a <fo:page-sequence> there should only be one <fo:flow> element which has to be placed after all the <fo:static-content> elements.

<< back next >>

Copyright © dpunkt.verlag GmbH 2004
Printing of the online version is permitted exclusively for private use. Otherwise this chapter from the book "XSL-FO in der Praxis" ("XSL-FO in practice") is subject to the same provisions as those applicable for the hardcover edition: The work including all its components is protected by copyright. All rights reserved, including reproduction, translation, microfilming as well as storage and processing in electronic systems.

dpunkt.verlag GmbH, Ringstraße 19B, 69115 Heidelberg, fon 06221-14830, fax 06221-148399, hallo@dpunkt.de