Formatting Object Basics

Formatting Object Basics
Page Layout
The root element of a formatting objects document is fo:root. This element contains one fo:layout-master-set element and one or more fo:page-sequence elements. The fo:page-sequence elements contain content; that is, text and images to be placed on the pages. The fo:layout-master-set contains templates for the pages that will be created.
When the formatter reads an XSL-FO document, it creates a page based on the first template in thefo:layout-master-set. Then it fills it with content from the fo:page-sequence. When it’s filled the first page, it instantiates a second page based on a template, and fills it with content. The process continues until the formatter runs out of content.
The root element
The fo:root element generally has an xmlns:fo attribute with the value and may (though it generally does not) have an id attribute. The fo:root element exists just to declare the namespace and be the document root. It has no direct effect on page layout or formatting.
Simple page masters
The page templates are called page masters. Page masters are similar in purpose to QuarkXPress master pages or PowerPoint slide masters. Each defines a general layout for a page including its margins, the sizes of the header, footer, and body area of the page, and so forth.
Each actual page in the rendered document is based on one master page, and inherits certain properties like margins, page numbering, and layout from that master page. XSL-FO 1.0 defines exactly one kind of page master, the fo:simple-page-master, which represents a rectangular page. The fo:layout-master-set contains one or more fo:simple-page-master elements that define master pages.

Future versions of XSL-FO will add other kinds of page masters, possibly including non-rectangular pages.

Each master page is represented by a fo:simple-page-master element. A fo:simple-page-master element defines a page layout, including the size of its before region, body region, after region, end region, and start region. Figure 19-2 shows the typical layout of these parts.
One thing that may not be obvious from this picture is that the body region overlaps the other four regions (though not the page margins); that is, the body is everything inside the thick black line including the start, end, before, and after regions.
The layout of the parts of a simple page of English text

In normal English text, the end region is the right side of the page and the start region is the left side of the page. This is reversed in Hebrew or Arabic text, because these languages are written from right to left. In almost all modern languages, the before region is the header and the after region is the footer, but this could be reversed in a language that wrote from bottom to top.

Simple page master properties
The fo:simple-page-master element has three main attributes:
• master-name: the name by which page sequences will reference this master page

• page-height: the height of the page

• page-width: the width of the page

If the page-height and page-width are not provided, then the formatter chooses a reasonable default based on the media in use (for example, 8.5″ × 11″).
Other attributes commonly applied to page masters include:
• The margin-bottom, margin-left, margin-right, and margin-top attributes, or the shorthand margin attribute

• The writing-mode attribute that determines which direction text flows on the page, for example, left-to-right or right-to-left or top-to-bottom

• The reference-orientation attribute that specifies in 90-degree increments whether and how much the content is rotated

For example, here is a fo:layout-master-set containing one fo:simple-page-master named US-Letter. It specifies an 8.5 × 11-inch page with half-inch margins on each side. It contains a single region, the body, into which all content will be placed.

  <fo:simple-page-master  master-name="US-Letter"

     page-height="11in"   page-width="8.5in"

     margin-top="0.5in"   margin-bottom="0.5in"

     margin-left="0.5in"  margin-right="0.5in">




The designer sets the size of the body (center) region, header, footer, end region, and start region, as well as the distances between them, by adding region child elements to the fo:simple-page-master. These are:
• fo:region-before

• fo:region-after

• fo:region-body • fo:region-start

• fo:region-end

The fo:region-before and fo:region-after elements each have an extent attribute that gives the height of these regions. Their width extends from the left side of the page to the right side. The fo:region-start and fo:region-end elements each have an extent attribute that specifies their widths.
Their height extends from the bottom of the start region to the top of the end region. (This assumes normal Western text. Details would be rotated in Chinese or Hebrew or some other non-right-to-left-top-to-bottom script.)
The fo:region-body does not have an extent attribute. Instead, the size of the body is everything inside the page margins. Thus, the region body overlaps the other four regions on the page. If you place text into the body and the other four regions, text will be drawn on top of other content. To avoid this, you must set the left margin of the body to be as large or larger than the extent of the start region, the top margin of the body to be as large or larger than the extent of the before region, and so on.
Each of the five regions of a simple page master may be filled with content from a fo:flow or fo:static-content element when the document is processed. However, these elements do not contain that content. Instead, they simply give the dimensions of the boxes the formatter will build to put content in. They are blueprints for the boxes, not the boxes themselves.
For example, this fo:simple-page-master creates pages with one-inch before and after regions. The region body will extend vertically from the bottom of the before region to the top of the after region. It will extend horizontally from the left side of the page to the right side of the page because there is no start or end region.
 <fo:simple-page-master master-name="table_page">

    <fo:region-before extent="1.0in"/>

    <fo:region-body margin-top="1.0in" margin-bottom="1.0in"/>

    <fo:region-after extent="1.0in"/>


For another example, here is a fo:layout-master-set that makes all outer regions one inch. Furthermore, the page itself has a half-inch margin on all sides.

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

       page-width="8.5in"   page-height="11in"

       margin-top="0.5in"   margin-bottom="0.5in"

       margin-left="0.5in"  margin-right="0.5in">

    <fo:region-start  extent="1.0in"/>

    <fo:region-before extent="1.0in"/>

    <fo:region-body   margin="1.0in"/>

    <fo:region-end    extent="1.0in"/>

    <fo:region-after  extent="1.0in"/>



The body regions from pages based on this page master will be 5.5 inches wide and 8 inches high. That’s calculated by subtracting the sum of the body region’s margins and the page margins from the size of the page.
Page sequences
In addition to a fo:layout-master-set, each formatting object document contains one or more fo:page-sequence elements. Each page in the sequence has an associated page master that defines how the page will look. Which page master this is, is determined by the master-reference attribute of the fo:page-sequence element.
This must match the name of a page master in the fo:layout-master-set. Listing 19-1 used a fo:simple-master-page named only to fill this role, but it is not uncommon to have more than one master page. In this case, the master pages might be grouped as part of a fo:page-sequence-master instead.
For instance, you could have one master page for the first page of each chapter, a different one for all the subsequent left-hand pages, and a third for all the subsequent right-hand pages. Or, there could be one simple page master for a table of contents, another for body text, and a third for the index. In this case, you use one page sequence each for the table of contents, the body text, and the index.
Each page sequence contains three child elements in this order:
1. An optional fo:title element containing inline content that can be used as the title of the document. This would normally be placed in the title bar of the browser window like the TITLE element in HTML

2. Zero or more fo:static-content elements containing text to be placed on every page

3. One fo:flow element containing data to be placed on each page in turn

The main difference between a fo:flow and a fo:static-content is that text from the flow isn’t placed on more than one page, whereas the static content is. For example, the words you’re reading now are flow content that only appear on this page, whereas the part and chapter titles at the top of the page are static content that is repeated from page to page.
The fo:flow element contains, in order, the elements to be placed on the page. As each page fills with elements from the flow, a new page is created with the next master page in the page sequence master for the elements that remain in the flow. With a simple page master, the same page will be instantiated repeatedly, as many times as necessary to hold all the content.
The fo:static-content element contains information to be placed on each page. For instance, it may place the title of a book in the header of each page. Static content can be adjusted depending on the master page. For instance, the part title may be placed on left-hand pages, and the chapter title on right-hand pages. The fo:static-content element can also be used for items such as page numbers that have to be calculated from page to page. In other words, what’s static is not the text, but the calculation that produces the text.
The fo:flow object holds the actual content, which will be placed on the instances of the master pages. This content is composed of a sequence of fo:block, fo:block-container, fo:table-and-caption, fo:table, and fo:list-block elements. This section sticks to basic fo:block elements, which are roughly equivalent HTML’s DIV elements. Later in this chapter, you learn more block-level elements that a flow can contain.
For example, here is a basic flow containing the names of several atoms, each in its own block:
<fo:flow flow-name=”xsl-region-body”>
The flow-name attribute of the fo:flow, here with the value xsl-region-body, specifies which of the five regions of the page this flow’s content will be placed in. The allowed values are:
• xsl-region-body

• xsl-region-before

• xsl-region-after

• xsl-region-start

• xsl-region-end

For example, a flow for the header has a flow-name value of xsl-region-before. A flow for the body would have a flow-name of xsl-region-body. Only one fo:flow is allowed in the same page sequence. The other four regions have to be filled with a fo:static-content if anything.
You can now put together a complete style sheet that lays out the entire periodic table. Listing 19-3 demonstrates this with an XSLT style sheet that converts the periodic table into XSL formatting objects. The flow grabs all the atoms and places each one in its own block. A simple page master named only defines an A4-sized master page in landscape mode with half-inch margins on each side.
Listing 19-3 A

basic style

sheet for the

periodic table

<?xml version="1.0"?>

<xsl:stylesheet version="1.0"



  <xsl:template match="/">

    <fo:root xmlns:fo="">


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

           page-width="297mm"  page-height="210mm"

           margin-top="0.5in"  margin-bottom="0.5in"

           margin-left="0.5in" margin-right="0.5in">




      <fo:page-sequence master-reference="A4">

        <fo:flow flow-name="xsl-region-body">

          <xsl:apply-templates select="//ATOM"/>





  <xsl:template match="ATOM">

    <fo:block><xsl:value-of select="NAME"/></fo:block>


Scroll to Top