Page Layout

When formatting content from a fo:page-sequence which has flow-name="chapter", Ibex looks at each of the conditional-page-master-reference elements and chooses which one will be active for the current page. This is done by evaluating conditions specified with the page-position attribute.

Using one layout for all pages

The first element in any FO file is the fo:root element which contains the whole FO tree defining the document and declares the XML namespaces used. Figure 7-1 shows a simple FO file.

<fo:root xmlns="http://www.w3.org/1999/XSL/Format">
	<fo:layout-master-set>
		<fo:simple-page-master master-name="layout" page-width="8.5in" page-height="8in">
			<fo:region-body region-name="body" margin="2.5cm"/>
		</fo:simple-page-master>
	</fo:layout-master-set>
	<fo:page-sequence master-reference="layout">
		<fo:flow flow-name="body">
			<fo:block>Hello world</fo:block>
		</fo:flow>
	</fo:page-sequence>
</fo:root>

Figure 7-1: Simple FO file

The first FO element within the fo:root element is the fo:layout-master-set element. This contains one or more fo:simple-page-master elements which define the layout of a page, including the width and height.

The simple-page-master element is like a template for a page, defining the page size and the areas on the page into which content will be placed. As content is read from a fo:flow, Ibex decides which simple-page-master to use as the basis for creating the current page. If there is only one fo:simple-page-master then it is always used. If there are several fo:simple-page-masters then a selection process is used to see which one applies to the current page.

The fo:simple-page-master element contains region elements such as fo:region-body which define an area on the page which can be filled with text or image content. There can be any number of fo:simple-page-master elements provided each has a unique master-name attribute.

Figure 7-2 shows an example of a fo:layout-master-set.

<fo:layout-master-set>
  <fo:simple-page-master master-name="front-page">
    <fo:region-body margin-right="2.5cm" margin-left="4cm" margin-bottom="4cm" margin-top="4cm" region-name="body" background-color="#eeeeee"/>
    <fo:region-after extent="3cm" region-name="footer" background-color='#dddddd'/>
  </fo:simple-page-master>
</fo:layout-master-set>

Figure 7-2: Example layout-master-set

This shows a fo:layout-master-set which contains a single fo:simple-page-master with a master-name of "front-page". This fo:simple-page-master defines a page which has two regions on which content can be rendered. For the purposes of this example the regions have background-colors defined to show them clearly.

Having defined a page layout which has a name, (defined by its master-name attribute) we then use the fo:page-sequence element to define the content of the document. The fo:page-sequence element has a master-name attribute which should match the master-name defined for a fo:simple-page-master (or a fo:page-sequence-master, more of which later). A fo:page-sequence for printing "Hello World" is shown in Figure 7-3.

<fo:page-sequence master-reference="front-page">
  <fo:flow flow-name="body">
    <fo:block>Hello World</fo:block>
  </fo:flow>
</fo:page-sequence>

Figure 7-3: page-sequence for hello world

A key thing to note is that the content of the fo:page-sequence is contained in a fo:flow element. For content of the flow to appear on the PDF page the flow-name attribute of the fo:flow element must match the region-name of a region on the page master specified by the master-reference on the fo:page-sequence. If the flow-name does not match a region-name, none of the content of this fo:flow will appear in the output document. It is important to understand this feature. It means that a fo:page-sequence can contain multiple fo:flow and fo:static-content elements each containing a fo:flow element with a different flow-name. Only fo:flow elements whose flow-name attribute matches a region-name defined in the current page sequence will appear. This is how we produce different formats for odd and even pages. In Figure 7-4 the master-name on the fo:simple-page-master should match the master-reference on the fo:page-sequence.

<fo:root xmlns="http://www.w3.org/1999/XSL/Format">
  <fo:layout-master-set>
    <fo:simple-page-master master-name="front-page">
      <fo:region-body margin-right="2.5cm" margin-left="4cm" margin-bottom="4cm" margin-top="4cm" region-name="
body
"/>
      <fo:region-after extent="3cm" region-name="footer"/>
    </fo:simple-page-master>
  </fo:layout-master-set>
  <fo:page-sequence master-reference="front-page">
    <fo:flow flow-name="body">
      <fo:block>Hello World</fo:block>
    </fo:flow>
  </fo:page-sequence>
</fo:root>

Figure 7-4: Matching flow and region names

Using different layouts for different pages

It is possible to define different page layouts for different pages. This can be done in two possible ways, either by assigning different page masters to different page sequences, or by using a page-master-alternatives element which chooses from a set of simple-page-master elements based on criteria such as the current page number.

Using different page masters for each page sequence

Using a different page master for each page sequence is useful when you can clearly divide the document into distinct sections. For example, this manual has a different page master for the front cover and for the pages in the table of contents. The page masters for this are shown in Figure 7-5.

<fo:layout-master-set>
	<fo:simple-page-master master-name="front-page" margin="1.5cm" page-height="297mm" page-width="210mm">
		<fo:region-body region-name="body" margin="0.75cm 0.5cm 0.75cm 3cm"/>
		<fo:region-before region-name="header" extent="2.5cm"/>
		<fo:region-after region-name="footer" extent="1cm"/>
		<fo:region-start extent="1cm" background-color="#eeeeee"/>
	</fo:simple-page-master>
						
	<fo:simple-page-master master-name="toc-page" margin="1.5cm" >
		<fo:region-body column-count="1" region-name="body" margin="0.75cm 0.5cm 1cm 3cm" margin-left="2cm" margin-right="1.5cm" />
		<fo:region-before region-name="header" extent="1cm"/>
		<fo:region-after region-name="footer" extent="0.75cm"/>
		<fo:region-start extent="2cm" />
		<fo:region-end region-name="end" extent="1.5cm" />
	</fo:simple-page-master>
</fo:layout-master-set>

Figure 7-5: Two page masters

Content is allocated to the two sections of the document using two separate page-sequences, as shown in Figure 7-6.

<fo:page-sequence master-reference="front-page">
	<fo:flow flow-name="body">
		<fo:block>
			content that appears in the body of the front page
		</fo:block>
	</fo:flow>
</fo:page-sequence>

<fo:page-sequence master-reference="toc-page">
	<fo:flow flow-name="body">
		<fo:block>
			content that appears in the table of contents
		</fo:block>
	</fo:flow>
</fo:page-sequence>

Figure 7-6: Allocating content to two page masters

When using this approach content from one flow always appears on pages with the same layout. Flowing content across different page layouts is described in the next section.

Using page master alternatives

Often it is desirable to have content flow continuously across pages with different layouts. This is done in the Ibex manual, where the pages are laid out like this: The three page masters are shown in Figure 7-7.

<fo:simple-page-master  master-name="chapter-odd-no-header">
	<fo:region-body region-name="body" margin="2.5cm 2.5cm 2.5cm 4.0cm"/>
	<fo:region-after region-name="footer-odd" extent="1.5cm" display-align="before"/>
</fo:simple-page-master>
				
<fo:simple-page-master master-name="chapter-even">
	<fo:region-body region-name="body" margin="2.5cm 2.5cm 2.5cm 4.0cm" column-count="1"/>
	<fo:region-before region-name="header-even" extent="1.5cm" display-align="after"/>
	<fo:region-after region-name="footer-even" extent="1.5cm" display-align="before"/>
</fo:simple-page-master>
								
<fo:simple-page-master  master-name="chapter-odd">
	<fo:region-body region-name="body" margin="2.5cm 2.5cm 2.5cm 4.0cm"/>
	<fo:region-before region-name="header-odd" extent="1.5cm" display-align="after"/>
	<fo:region-after region-name="footer-odd" extent="1.5cm" display-align="before"/>
</fo:simple-page-master>

Figure 7-7: Page masters for three different layouts

To make content from a single flow element span multiple pages with different page layouts we use a fo:page-sequence-master element as shown in Figure 7-8. This element contains a fo:repeatable-page-master-alternatives element, which in turn contains a set of fo:conditional-page-master-reference elements.

As a page is created, each conditional-page-master-reference is considered in turn, starting from the first one. The first one found whose conditions are satisfied will determine the page master for the current page. Since alternatives are considered in the order in which they appear in the FO, the order in which the alternatives are listed is important. When the first page of the chapter is being created, the page-position="first" condition is true, so the first conditional-page-master-reference will be chosen because it has page-position = "first". This has master-reference = "chapter-odd-no-header", so the simple-page-master with master-name = "chapter-odd-no-header" becomes the active page master for the first page of the chapter.

When the second page of the chapter is being created, the page-position="first" is no longer true so the conditions on the next conditional-page-master-reference will be evaluated.

Although not shown in this example, other attributes such as blank-or-not-blank can be used to control the selection of one of the alternatives.

<fo:page-sequence-master master-name="chapter" >
		<fo:repeatable-page-master-alternatives>
				<fo:conditional-page-master-reference page-position="first" master-reference="chapter-odd-no-header"/>
				<fo:conditional-page-master-reference odd-or-even="odd" master-reference="chapter-odd"/>
				<fo:conditional-page-master-reference odd-or-even="even" master-reference="chapter-even"/>
		</fo:repeatable-page-master-alternatives>
</fo:page-sequence-master>

Figure 7-8: The page-sequence-master element