Pages
XSL-FO documents are composed of pages, which are in turn composed of several different regions. When a document is rendered using Formatting Objects, text is flowed from page to page as required until the entire document has been generated.
Each page is composed of five regions, which are generated by the following object elements:
fo:region-body
The fo:region-body object creates the body region of the page. This region actually contains all the page content, including the other region-before, region-after, region- start, and region-end areas. This can be quite confusing—the naming scheme would imply that one region comes before or after the other, but, in fact, the coordinates of the regions have to be set appropriately to ensure that they do not overlap.
fo:region-before
The region-before area is located at the top of the page, inside the margin-top. It can be used to place header information on a page, but keep in mind that unless formatted otherwise, it will naturally overlap with the body region.
fo:region-after
The region-after area is located at the bottom of the page, and is ended at the margin-bottom. It can be used as a footer area on the page; however, like the region-before, it may overlap with the body region.
fo:region-start
The region-start area is located on the left side of the page, when used with a Western-based language. It is bounded on the left by the margin-left. Similar to the other regions, it naturally overlaps the body region.
fo:region-end
The region-end area is located on the right side of the page, bounded by the margin-right. It also overlaps the body region.
Caution
Region placement is based on the assumption of top-to-bottom, left-to-right text. Therefore, in the standard model, the region-start object occurs on the left, and the region-end object occurs on the right, because Western text is written left-to-right. However, if you are working with a character set and language such as Arabic or Hebrew, which is written right-to-left, the placement of these areas will be reversed.
In addition to these body regions, pages also have margins that can be expressed with the following formatting object elements:
fo:margin-top
fo:margin-bottom
fo:margin-left
This object defines the margin on the left side of the page.
fo:margin-right
This object defines the margin on the right side of the page.
Unlike the body regions, the margins do not overlap with the other areas on the page. These objects also do not change with respect to the orientation of the text. The left margin is always the left margin.
Page Masters
Because the model for laying out documents in XSL-FO is based on pages, there exists a mechanism for defining master pages, which serve as templates for the pages generated by the XSL processor when the document is being rendered.
Page masters in XSL-FO function similarly to page masters in other graphic design/layout programs, such as QuarkXPress. After defining the properties associated with a master page, that master page can then be referenced within the stylesheet to construct a page, which, in turn, inherits the properties of the page master. Let's see how this works in XSL-FO.
First, page masters are contained in an object element called the layout-master-set. This is a container object, which can be used to group multiple page masters for complex documents. For example, you may want to have multiple masters for different pages in your document, such as a title page, or other specially formatted pages.
All page masters are defined using the fo:simple-page-master object, which is used to manipulate the actual properties of the physical page layout. You can create any number of simple-page-master pages, which can then be used in conjunction with the page-sequence-master to create more complex layout schemes.
For example, if we wanted to define a page master for a simple, 8.5×11-inch letter-size page, we would use
<fo:layout-master-set>
<fo:simple-page-master master-name="Letter"
page-width="8.5in"
page-height="11.0in"
margin-top="0.5in"
margin-bottom="0.5in"
margin-left="0.5in"
margin-right="0.5in">
<fo:region-body/>
</fo:simple-page-master>
</fo:layout-master-set>
The page-width and page-height properties define the size of the page, and can be expressed using the following units of measure:
Each of the four margins can also be specified using these units of measure. In this case, because we are defining a simple, blank page, we need to use only a single region for the body; any content we place on the page will then be flowed into that region. Here's another example of a simple master, which defines a legal-size page:
<fo:layout-master-set>
<fo:simple-page-master master-name="Legal"
page-width="8.5in"
page-height="14.0in"
margin-top="0.5in"
margin-bottom="0.5in"
margin-left="0.5in"
margin-right="0.5in">
<fo:region-body/>
</fo:simple-page-master>
</fo:layout-master-set>
Note
For those curious about international paper sizes, http://www.cl.cam.ac.uk/~mgk25/iso-paper.html has a good explanation of the various sizes available.
Now, if we wanted to make use of the region areas on the page, we could do so by defining the size and margins of the regions in the page master, and then utilizing those regions elsewhere in the document.
For example, let's say we wanted to create a letterhead, with a header and a footer that would appear on the page. We could do this by utilizing the region-before and region-after areas.
The length of the region-before and region-after areas is determined by using the extent property. For example, to define a header 1 inch, we would use
<fo:region-before extent="1.0in"/>
To define the footer, we would use
<fo:region-after extent="1.0in"/>
Next, in defining the region-body, we need to make use of the margin properties to make sure that the body region does not overlap our header and footer. Remember, the body naturally encompasses the before, after, start, and end areas, so by using the margin properties, we make sure that the body content is separated from the header/footer areas:
<fo:region-body margin-top="1.0in" margin-bottom="1.0in"/>
If we put those objects together into a page master, we have a page with a header and footer which we could use as a letterhead—for example:
<fo:layout-master-set>
<fo:simple-page-master master-name="Letter"
page-width="8.5in" page-height="11.0in"
margin-top="0.5in" margin-bottom="0.5in"
margin-left="0.5in" margin-right="0.5in">
<fo:region-before extent="1.0in"/>
<fo:region-body margin-top="1.0in" margin-bottom="1.0in"/>
<fo:region-after extent="1.0in"/>
</fo:simple-page-master>
</fo:layout-master-set>
Listing 10.1 shows how these regions could then be used as a header and a footer, containing information such as might be included on a company letterhead. Don't worry about how the block elements are formatted for now—we will cover those shortly. However, note how the simple-page-master is formatted and then referenced by the page-sequence.
Listing 10.1. An Example of Using Regions to Establish Page Header and Footer Areas
<?xml version="1.0"?>
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
<fo:layout-master-set>
<fo:simple-page-master master-name="Letter"
page-width="8.5in" page-height="11.0in"
margin-top="0.5in" margin-bottom="0.5in"
margin-left="0.5in" margin-right="0.5in">
<fo:region-before extent="1.0in"/>
<fo:region-body margin-top="1.0in" margin-bottom="1.0in"/>
<fo:region-after extent="1.0in"/>
</fo:simple-page-master>
</fo:layout-master-set>
<fo:page-sequence master-name="Letter">
<fo:static-content flow-name="xsl-region-before">
<fo:block font-size="18pt" font-family="serif"
font-weight="bold" text-align="center">
Mythical Company, Inc.
<fo:leader leader-pattern="rule" leader-length="7.0in" />
</fo:block>
</fo:static-content>
<fo:static-content flow-name="xsl-region-after">
<fo:block font-size="18pt" font-family="serif" text-align="center">
<fo:leader leader-pattern="rule" leader-length="7.0in" />
1-800-555-1212 or e-mail [email protected]
</fo:block>
</fo:static-content>
<fo:flow flow-name="xsl-region-body">
<fo:block font-size="12pt" font-family="serif">
The contents of the letter...
</fo:block>
</fo:flow>
</fo:page-sequence>
</fo:root>
|
The rendered results for the stylesheet in Listing 10.1 is shown in Figure 10.2.
Figure 10.2. The rendered results of the letterhead.fob stylesheet—note the region-begin and region-end areas rendered at the top and bottom of the page.
Although so far we have looked at only the simple-page-master object, there are a number of other ways to use page masters. By using the page-sequence-master object, you can group a number of different types of references to simple-page-masters together. This is done by using a number of different reference objects, such as
fo:single-page-master-reference
The single-page-master-reference can be used to describe a page master that is limited to one page in length. Under normal circumstances, pages are flowed, one to the next, until the document has been rendered. Using a single-page-master-reference limits the display to one page. This could be used to create a master for a title page, for example.
fo:repeatable-page-master-reference
Even though the simple-page-master does flow, you might want to create a repeatable-page-master-reference to coincide with the single page master, which could be used for the rest of the document—say, the report that follows a title page.
The conditional-page-master-reference allows you to create references to a set of page masters, which can then be used depending on certain conditions, such as being the first or last page of the document. For example, if we wanted to create a set of page masters for a chapter, with a Title Page master, a master for the chapter text, and another master for an index on the last page, we would use a conditional master set:
<fo:layout-master-set>
<fo:page-sequence-master master-name="chapter">
<fo:repeatable-page-master-alternatives>
<fo:conditional-page-master-reference page-position="first"
master-name="title_page"/>
<fo:conditional-page-master-reference page-position="rest"
master-name="chapter_text"/>
<fo:conditional-page-master-reference page-position="last"
master-name="index"/>
</fo:repeatable-page-master-alternatives>
</fo:page-sequence-master>
</fo:layout-master-set>
Each of the conditional-page-master-reference objects in turn references a simple-page-master definition that constructs the page layout itself. The conditional-page-master- reference allows you to create page masters that are used depending on one of three criteria:
page-position— The page-position can be first, last, rest, or any, which are used to denote the position of the page(s) relative to the other pages in the document.
odd-or-even— The odd-or-even trait can be used to denote either all odd pages, all even pages, or any page.
blank-or-not-blank— The blank-or-not-blank trait can denote blank pages, not-blank pages, or any page.
The use of masters can be very flexible, and provides the fine level of control that graphic designers are accustomed to, although as the control level increases, so does the complexity of the stylesheet.
Page Sequences
Page sequences consist of multiple document pages as rendered by the XSL processor.
For simpler documents, the page-sequence object is used to create instances of pages, based on the page master:
<?xml version="1.0"?> <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"> <fo:layout-master-set> <fo:simple-page-master master-name="the_page_master"> <fo:region-body/> </fo:simple-page-master> </fo:layout-master-set> <fo:page-sequence master-name="the_page_master"> <fo:flow flow-name="xsl-region-body"> <fo:block/> </fo:flow> </fo:page-sequence> </fo:root>
The page-sequence has a master-name property that is used to reference the appropriate page master. Unless you are using a page master that restricts the number of pages in the document, the page-sequence will be used to create as many pages as necessary to render the complete document.