Page Regions in XSL-FO

Inasmuch as I used this new sequence of images in my recent XSLT and XSL-FO talk at XML Summer School 2011, here’s an outline of page regions in XSL-FO.

The fo:simple-page-master FO in XSL 1.1 defines the dimensions of a page. A document may have more than one fo:simple-page-master, and the same fo:simple-page-master may be used in multiple contexts. A fo:simple-page-master has up to five regions: fo:region-body, fo:region-start, fo:region-end, fo:region-start, and fo:region-end.  Only fo:region-body is required.  The adjacent figure shows one arrangement of the regions.

Effect of writing mode

The FO names for the outer regions include “-before”, “-after”, “-start”, and “-end” rather than “-top”, “-bottom”, “-left”, and “-right” since the relative position of the regions depends on the writing mode.

This figure shows the arrangement of the regions for both “lr” (short for “tb-lr’ for “top-to-bottom, right-to-left”) and “rl” (you can work it out) writing modes. As you can imagine, the arrangements would be different again for “tb-rl” and “bt-rl”, etc.

Regions have default names

Regions have names, and content is directed to the page regions based on the region’s name, not on its FO type (a.k.a. its “class”). This time, the figure shows the default, initial name for each page region FO, which just happens to look a lot like the FO’s name, such as “xsl-region-body” for fo:region-body.

Or use your own names

But you don’t have to stick with the initial names. You can define the regions with any name, such as “my-before”, “my-end”, or even “George”, provided it’s:

  • A valid name. It has to be, in XML terminology, a NCName, which means, e.g., it can’t contain a colon and has to start with a letter (or other allowed character).
  • Unique within the region names for the page master
  • Not the initial name for a different class of region: i.e., you can’t call your fo:region-before “xsl-region-after” and expect things to work

An additional proviso that works across page masters is that you can’t use the same name on different region types on different page masters. So “George” can’t be a fo:region-before on one page master and fo:region-start on another. Sorry, George.

Reusing region names across page masters

The flip-side of the proviso above is that you can use the same region name for the same region on different page masters. This figure shows three page masters that will separately be used for:

  • The first page in a page sequence;
  • The odd pages; and
  • The even pages.

Since (for conventional, “tb-lr” documents, anyway) the first page of the first page sequence is numbered “1” and appears on the right-hand (recto) side of a spread and (conventionally, again) following page sequences also start on an odd-numbered, recto page, the page master for the first pages often has the same header and/or footer as other pages or other odd-numbered pages. In this case, the “First” page master and the “Odd” page master have the same names for the same regions except xsl:region-end, which is named “First-Outside” on the “First” page master and “Odd-Outside” on the “Odd” page master. (Note that repetition of “First” and “Odd” in region names is for convenience only and isn’t a requirement of XSL-FO.)

Arrange page masters into sequence

When the multiple page masters are used to make a sequence of pages (using fo:page-sequence-master, as you do), you can see the repetition of the regions across the multiple pages. When overlaid over pages from the exercises used in the course, you can see the same footer in use on the odd pages, a different footer on the even pages, the different fo:region-end content on the first and the later odd pages, and (in this case) nothing at all in the fo:region-start of any page.

Content from fo:page-sequence

The content of the page regions, including the content of the fo:region-body, comes from the fo:page-sequence: (conventionally) the content of the outer regions are defined in fo:static-content, and the content of the fo:region-body, in the fo:flow.

The correspondence between fo:static-content and an outer region is by name: put simply, when a page master for a page has a region with the same name as the “flow-name” property of a fo:static-content of the current fo:page-sequence, the areas from the formatting objects within the fo:static-content are repeated within that region on that page. (The not put simply version could see things rearranged through a XSL 1.1 fo:flow-map and multiple fo:flow with content directed to multiple regions on the page, but that’s something for another time.)

One thought on “Page Regions in XSL-FO

Comments are closed.