Page Sequences and Page Numbering

So far, Ive used the same page master for all pages in these XSL-FO documents. If the content of a document fills more than one page, the XSL-FO processor uses the same page master for all subsequent pages.

However, you might want to use different page masters for different locations in your document. For example, you may want to format the first page differently from the subsequent pages. Using XSL-FO, you can do this.

Each <fo:page-sequence> element, which Ive used in all XSL-FO examples, references either a page master or an <fo:page-sequence-master> element. Using the <fo:page-sequence-master> element, you can specify different page masters to use in a sequence.

The following example, pages.fo, shows how this works. In this case, I create one simple page master, first, for the first page, starting the text part way down on the page by setting the <fo:region-body> elements margin-top property to 50mm:

 <?xml version="1.0" encoding="utf-8"?>  <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">    <fo:layout-master-set>          <fo:simple-page-master margin-right="20mm" margin-left="20mm"              margin-bottom="10mm" margin-top="10mm" page-width="300mm"              page-height="400mm" master-name="first">              <fo:region-body margin-right="0mm" margin-left="0mm"                  margin-bottom="10mm" margin-top="50mm"/>              <fo:region-after extent="10mm"/>              <fo:region-before extent="10mm"/>          </fo:simple-page-master>          .          .          .

And I create a new page master, rest, for all the other pages, starting the text on those pages near the top of the page by setting the <fo:region-body> elements margin-top property to 20mm:

 <?xml version="1.0" encoding="utf-8"?>  <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">    <fo:layout-master-set>          <fo:simple-page-master margin-right="20mm" margin-left="20mm"              margin-bottom="10mm" margin-top="10mm" page-width="300mm"              page-height="400mm" master-name="first">              .              .              .          </fo:simple-page-master>          <fo:simple-page-master margin-right="25mm" margin-left="25mm"              margin-bottom="15mm" margin-top="15mm" page-width="300mm"              page-height="400mm" master-name="rest">              <fo:region-body margin-right="0mm" margin-left="0mm"                  margin-bottom="10mm" margin-top="20mm"/>              <fo:region-after extent="10mm"/>              <fo:region-before extent="10mm"/>          </fo:simple-page-master>          .          .          .

To create a page sequence master that uses the simple page masters first and rest, I use the <fo:page-sequence-master> element:

 <?xml version="1.0" encoding="utf-8"?>  <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">    <fo:layout-master-set>          <fo:simple-page-master margin-right="20mm" margin--left="20mm"          margin-bottom="10mm" margin-top="10mm" page-width="300mm"          page-height="400mm" master-name="first">          .          .          .      </fo:simple-page-master>      <fo:simple-page-master margin-right="25mm" margin-left="25mm"          margin-bottom="15mm" margin-top="15mm" page-width="300mm"          page-height="400mm" master-name="rest">          .          .          .      </fo:simple-page-master>      <fo:page-sequence-master master-name="sequence" >          .          .          .      </fo:page-sequence-master>  </fo:layout-master-set>

You can use this property with <fo:page-sequence-master> :

master-name

In this case, Ive just named the new page sequence sequence. The type of page sequence master Im creating here is a repeatable page master , and you use the <fo:repeatable-page-master-alternatives> element to specify the names of the page masters you want to use in the new sequence:

 <fo:page-sequence-master master-name="sequence">      <fo:repeatable-page-master-alternatives>      .      .      .      </fo:repeatable-page-master-alternatives>  </fo:page-sequence-master>

You can use this property with <fo:repeatable-page-master-alternatives> to indicate how many times you want the sequence to repeat:

maximum-repeats

Finally, you specify the page masters that are to be used in this sequence master with the <fo:conditional-page-master-reference> element. This element references a page master with the master-name property, and that page master is used when a specified condition is met. To match the first page, you set the page-position property to first, and to match the rest of the pages, you set page-position to rest:

 <fo:page-sequence-master master-name="sequence" >              <fo:repeatable-page-master-alternatives>  <fo:conditional-page-master-reference master-name="first"                      page-position="first" //>                  <fo:conditional-page-master-reference master-name="rest"                      page-position="rest" //>              </fo:repeatable-page-master-alternatives>          </fo:page-sequence-master>

You can use the following properties with <fo:conditional-page-master-reference> :

master-name
page-position
odd-or-even
blank-or-not-blank

Now when I create a page sequence with <fo:page-sequence> , I specify that the XSL-FO processor should use the sequence master, sequence, that I just created by setting the <fo:page-sequence> elements master-name attribute:

 <fo:page-sequence master-name="sequence">          .          .          .

Now that Im dealing with multiple pages, I want to also add page numbers to the pages in the document. The XSL-FO processor replaces the element <fo: page-number > with the current page number, so creating page numbering is no problem. To display the page number at the top of each page, I create a page header with the <fo:static-content> element.

There are two kinds of flow objects: <fo:static-content> and <fo:flow> . Youve already seen how to use <fo:flow> to add pages to the flow of a document. You use the <fo:static-content> element to add headers and footers to document. You can use this property with <fo:static-content> :

flow-name

To create a header, all I have to do is to place the <fo:static-content> element before the <fo:flow> element in the page sequence:

 <fo:page-sequence master-name="sequence">          <fo:static-content flow-name="xsl-region-before">              <fo:block text-align="end"                  font-size="24pt"                  font-family="sans-serif"                  line-height="36pt" >                  Sample Document p. <fo:page-number/>              </fo:block>          </fo:static-content>          <fo:flow flow-name="xsl-region-body">          .          .          .

Setting the initial page number

To set the initial page number of a page sequence, you can use the <fo:page-sequence> elements initial-page-number property. This enables you, for example, to format chapters separately, starting each with the correct page number.

Finally, all thats left in pages.fo is to add some sample text to format so that the document contains more than one page; I color this filler text gray so its not distracting:

Listing 12.8 pages.fo

 <?xml version="1.0" encoding="utf-8"?>  <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">    <fo:layout-master-set>          <fo:simple-page-master margin-right="20mm" margin-left="20mm"              margin-bottom="10mm" margin-top="10mm" page-width="300mm"              page-height="400mm" master-name="first">              <fo:region-body margin-right="0mm" margin-left="0mm"                  margin-bottom="10mm" margin-top="50mm"/>              <fo:region-after extent="10mm"/>              <fo:region-before extent="10mm"/>          </fo:simple-page-master>          <fo:simple-page-master margin-right="25mm" margin-left="25mm"              margin-bottom="15mm" margin-top="15mm" page-width="300mm"              page-height="400mm" master-name="rest">              <fo:region-body margin-right="0mm" margin-left="0mm"                  margin-bottom="10mm" margin-top="20mm"/>              <fo:region-after extent="10mm"/>              <fo:region-before extent="10mm"/>          </fo:simple-page-master>          <fo:page-sequence-master master-name="sequence" >              <fo:repeatable-page-master-alternatives>                  <fo:conditional-page-master-reference master-name="first"                      page-position="first" //>                  <fo:conditional-page-master-reference master-name="rest"                      page-position="rest" //>              </fo:repeatable-page-master-alternatives>          </fo:page-sequence-master>      </fo:layout-master-set>      <fo:page-sequence master-name="sequence">          <fo:static-content flow-name="xsl-region-before">              <fo:block text-align="end"                  font-size="24pt"                  font-family="sans-serif"                  line-height="36pt" >                  Sample Document p. <fo:page-number/>              </fo:block>          </fo:static-content>          <fo:flow flow-name="xsl-region-body">              <fo:block font-size="36pt" font-family="Times"                  text-align="center"                  space-after="24pt">                  Sample Document              </fo:block>              <fo:block font-size="24pt" font-family="sans-serif" color="gray">               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.               Sample Text. Sample Text. Sample Text. Sample Text. Sample Text. Sample  Text.           </fo:block>          </fo:flow>      </fo:page-sequence>  </fo:root>

And thats it. You can see the first page created by pages.fo in Figure 12.8; as you can see in that figure, the text starts some distance down the first page.

Figure 12.8. A first page as formatted with XSL-FO.

The text on the second page, on the other hand, starts near the top, as you see in Figure 12.9.

Figure 12.9. A second page as formatted with XSL-FO.

As you can see in Listing 12.8, I use a lot of lines that hold nothing but the words Sample Text. in pages.fo to make sure theres enough text to create a multiple-page document. However, you dont actually need a lot of text to skip to the next page; you can also set the <fo:block> elements break-after property to page, which causes the XSL-FO processor to skip to the next page after the current block:

 <fo:flow flow-name="xsl-region-body">    <fo:block font-size="36pt" font-family="Times" text-align="center"    space-after="24pt">    Sample Document    </fo:block>    <fo:block font-size="24pt" font-family="sans-serif" color="gray"        break-after="page">        Sample Text. Sample Text. Sample Text. Sample Text. Sample Text.        Sample Text.        Sample Text. Sample Text. Sample Text. Sample Text. Sample Text.        Sample Text.    </fo:block>    <fo:block font-size="24pt" font-family="sans-serif" color="gray">        Sample Text. Sample Text. Sample Text. Sample Text. Sample Text.        Sample Text.        Sample Text. Sample Text. Sample Text. Sample Text. Sample Text.        Sample Text.    </fo:block>  </fo:flow>

Thats all it takes. Now the XSL-FO processor skips to the next page after the block. You can use the following properties and settings to create breaks:

break-after. Specifies that the last area generated by formatting this formatting object shall be the last one placed in a particular context. Set to auto column page even-page odd-page inherit.
break-before. Specifies that the first area generated should be the first one placed in a specific context. Set to auto column page even-page odd-page inherit.

Heres another example showing how to use page sequences. If you take a look at a book printed in Western languages such as English, German, or French, you see that even-numbered pages are typically on the left, and odd-numbered pages are on the right. You can format even and odd pages differently: for example, you can allow extra margin space near the books binding, which means adding extra left-margin space for odd pages and extra right-margin space for even pages.

To implement that, you can use the odd-or-even attribute of the <fo:conditional-page-master-reference> element. You can set the odd-or-even attribute to even or odd to select even or odd pages respectively, as follows :

 <?xml version="1.0" encoding="utf-8"?>  <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">      <fo:layout-master-set>          <fo:simple-page-master margin-right="50mm" margin-left="20mm"              margin-bottom="10mm" margin-top="10mm" page-width="300mm"              page-height="400mm" master-name="leftpage">              <fo:region-body margin-right="0mm" margin-left="0mm"                  margin-bottom="10mm" margin-top="50mm"/>              <fo:region-after extent="10mm"/>              <fo:region-before extent="10mm"/>          </fo:simple-page-master>          <fo:simple-page-master margin-right="20mm" margin-left="50mm"              margin-bottom="10mm" margin-top="10mm" page-width="300mm"              page-height="400mm" master-name="rightpage">              <fo:region-body margin-right="0mm" margin-left="0mm"                  margin-bottom="10mm" margin-top="20mm"/>              <fo:region-after extent="10mm"/>              <fo:region-before extent="10mm"/>          </fo:simple-page-master>          <fo:page-sequence-master master-name="alternatingpages">              <fo:repeatable-page-master-alternatives>                  <fo:conditional-page-master-reference master-name="rightpage"                      odd-or-even="odd" />                  <fo:conditional-page-master-reference master-name="leftpage"                      odd-or-even="even" />              </fo:repeatable-page-master-alternatives>          </fo:page-sequence-master>      </fo:layout-master-set>      <fo:page-sequence master-name="alternatingpages">          .          .          .

Thats all it takes. Now right-hand pages have extra left-margin space near the books binding, and left-hand pages have extra right-margin space as well.

As you can see, theres a lot to the XSL-FO formatting objects, and as mentioned earlier, theres a lot more that this book doesnt have the space to cover. For more details, take a look at the W3C site, www.w3.org/TR/xsl/. Not many software packages can put formatting objects to work yet, although thats going to change in the future.

Thats it for XSL-FOand thats it for this book. Youve seen all kinds of XSLT transformations here, from XML to XML, to HTML, to XHTML, to RTF, to plain text, to JavaScript, to SQL-based databases, and now to XSL-FO. Youve seen all the available elements, attributes, and functions available in XSLT. And youve seen many working examples. All that remains is for you to put all this power to work for yourself. Best of luck to you in your XSLT work!