Masters & Regions

Page layout setup starts with a master set layout, invoked by the <fo:layout-master-set> tag. Its contents consist of individual master definitions for a style sheet. For all intents and purposes, masters are basically page templates but let's stick to the name masters so as not to confuse them with actual XSL templates.

Master definition

Each master is defined using the <fo:simple-page-master> tag. It specifies page margins, height and width, as well as the master's name via the master-name attribute. The name enables us to reference a specific master later in the style sheet.

The master definition can, among other things, contain region definitions. Headers and footers are both examples of regions. Here are all the possibilities:

• <fo:region-body> defines the body of a page
• <fo:region-before> denotes a header
• <fo:region-after> specifies a footer
• <fo:region-start> defines a region shown to the left of the body
• <fo:region-end> specifies a region displayed to the right of the body

(The rest of this tutorial ignores the start and end regions as they are used far less frequently than the other three.)

A region can have a name - supplied via the region-name attribute - enabling us to reference that region later in the code. Name your regions, they will become far more reusable that way.

Put together, it looks something like this (let's assume that the used variables exist in the processing context):

<fo:simple-page-master
  master-name="onlyPage"
  margin="{$pageMarginTop} {$pageMarginRight} {$pageMarginBottom} {$pageMarginLeft}"
  page-height="{$pageHeightFull}"
  page-width="{$pageWidthFull}">
  <fo:region-before
    region-name="header-first"
    extent="{$headerFirstHeight}"/>
  <fo:region-body
    region-name="body"
    margin-top="{$bodyMarginTop + $headerFirstHeight}"
    margin-bottom="{$footerLastHeight}"/>
  <fo:region-after
    region-name="footer-last"
    extent="{$footerLastHeight}"/>
</fo:simple-page-master>

The code above defines a master called onlyPage with the given properties - page margin, height and width. It also specifies three regions, namely a header, body and a footer, that can be referenced later by their names: header-first, body and footer-last, respectively.

The extent attribute sets the size of a region, i.e. the height of the header and the footer in our scenario.

Body margin

Note how the margins on the body are computed. If you are like me, you would expect the margin-top and margin-bottom attributes on the body to specify the distance from the bottom of the header and the footer. This is not how it works though, they denote the distance from the top of the page and bottom of the page, respectively.

This implies that the value of the margin-top on the body needs to be equal to or greater than the value of the extent on the header; the same applies to margin-bottom and the extent on the footer. If you fail to follow this rule, you are risking an overflow.

Do you feel it is somewhat counter-intuitive? So do I.