Sams Teach Yourself XML in 21 Days

Recommended Book

Sams Teach Yourself XML in 21 Days, 3rd Edition

Learn More Buy

Recommended Book

Recommended Book 

Sams Teach Yourself XML in 21 Days, 3rd Edition

Learn More Buy

Building an XSL-FO Document

Now you've seen XSL-FO and gotten an overview of what objects and properties are available; the next step is to see how XSL-FO works by understanding the XSL-FO example. The following sections describe the elements that are involved in the example.

Using <fo:root>

The document element of XSL-FO documents has to be <fo:root> (although, of course, you can give the namespace any name, not just fo:). In the sample XSLT style sheet, you converted the sample XML document's document element, <states>, into <fo:root> this way:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:fo="http://www.w3.org/1999/XSL/Format"
    version='1.0'>

    <xsl:template match="states">

           <fo:root>
        .
        .
        .

The <fo:root> element can contain both a master set layout and page sequences.

The master set layout, which uses the <fo:layout-master-set> element, describes the masters, or templates, that you want to use in the document. You can specify the default page layout, such as margin sizes, here.

The page sequences, which use the <fo:page-sequence> element, specify the format for a sequence of pages. For example, you might give a series of pages the same headers and footers.

The example uses both a master set layout and page sequences, so you can see what they both do.

Using <fo:layout-master-set>

In XSL-FO you can use a master as a template for a page, a sequence of pages, or a region on a page. After you create a master, including specifying fonts and margin sizes, you can use it in a page sequence. For example, to create master templates, you can use the <fo:layout-master-set> element:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:fo="http://www.w3.org/1999/XSL/Format"
    version='1.0'>

    <xsl:template match="states">
        <fo:root>

            <fo:layout-master-set>
    .
    .
    .

Now you list the masters you want to use in the document in the <fo:layout-master-set> element. For example, you can create a master for each page by using the <fo:simple-page-master> element. You can also create page sequence masters to format pages in a sequence (as when you alternate odd/even page formatting for the left and right sides of a book). In this case, you can format the main page by using an <fo:simple-page-master> element, as described in the next section.

Using <fo:simple-page-master>

You use the page master <fo:simple-page-master> to create a template for a page and outline what goes where. After you create a page master, you can use it where you want in a document. Currently, the XSL specification supports only the <fo:simple-page-master> page master. These are the properties you can use in this element to define the page master:

• Block margin properties: margin-top, margin-bottom, margin-left, margin-right, space-before, space-after, start-indent, and end-indent
• master-name
• page-height
• page-width
• reference-orientation
• writing-mode

In today's example, the page master is named mainPage. You can set the page height, width, and margins like this:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:fo="http://www.w3.org/1999/XSL/Format"
    version='1.0'>

    <xsl:template match="states">
        <fo:root>

            <fo:layout-master-set>
                 <fo:simple-page-master master-name="mainPage"

                        page-height="300mm" page-width="200mm"

                        margin-top="20mm" margin-bottom="20mm"

                        margin-left="20mm" margin-right="20mm">
    .
    .
    .

That lays out the overall geometry of the page, but there's more to the story: You can also lay out regions in a page, such as the header, footer, and body. You can have up to five regions in a page master in the XSL-FO 1.0 specification:

• Body— The body region is the body of the page. To create this region, you use <fo:region-body>.
• Before— The before region is the header. To create this region, you use <fo:region-before>.
• After— The after region is the footer. To create this region, you use <fo:region-after>.
• Start— The start region appears to the left of the body. To create this region, you use <fo:region-start>.
• End— The end region appears to the right of the body. To create this region, you use <fo:region-end>.

Each of the region elements also has a number of properties that you can use, as listed here:

• Border, padding, and background properties: background-attachment, background-color, background-image, background-repeat, background-position-horizontal, background-position-vertical, border-before-color, border-before-style, border-before-width, border-after-color, border-after-style, border-after-width, border-start-color, border-start-style, border-start-width, border-end-color, border-end-style, border-end-width, border-top-color, border-top-style, border-top-width, border-bottom-color, border-bottom-style, border-bottom-width, border-left-color, border-left-style, border-left-width, border-right-color, border-right-style, border-right-width, padding-before, padding-after, padding-start, padding-end, padding-top, padding-bottom, padding-left, and padding-right
• Block margin properties: margin-top, margin-bottom, margin-left, margin-right, space-before, space-after, start-indent, and end-indent
• clip
• column-count
• column-gap
• display-align
• extent
• overflow
• region-name
• reference-orientation
• writing-mode

Using <fo:region-body> and <fo:region-after>

In today's example, you set the margins of the body region by using the available margin properties. In addition, you can set the width or height of the other four regions by using the extent property, as in the following markup, which sets the footer region to 20mm height:

<xsl:template match="states">
    <fo:root>

        <fo:layout-master-set>
             <fo:simple-page-master master-name="mainPage"
                 page-height="300mm" page-width="200mm"
                 margin-top="20mm" margin-bottom="20mm"
                 margin-left="20mm" margin-right="20mm">

                 <fo:region-body

                      margin-top="0mm" margin-bottom="10mm"

                      margin-left="0mm" margin-right="0mm"/>


                    <fo:region-after extent="20mm"/>
             </fo:simple-page-master>
         </fo:layout-master-set>
    .
    .
    .

You have now completed the page master you'll use in this document. Besides a page master, you also need to define a page sequence when you format documents in XSL-FO, and that's coming up next.

Using <fo:page-sequence>

A page sequence is a run of pages that are part of a group, such as a chapter in a book or a section in a report. You create page sequences by using the <fo:page-sequence> element. You can use page sequences to alternate page number for even/odd pages in a book, for example. Each such element refers to a page master such as the one you've already created and uses that page master to format its pages.

These are the properties you can use with the <fo:page-sequence> element:

• country
• format
• language
• letter-value
• grouping-separator
• grouping-size
• id
• initial-page-number
• force-page-count
• master-name
• master-reference

You specify the name of the page master you want to use in a page sequence by using the master-reference attribute. In today's example, the page master is named mainPage, so here's how the page sequence starts out:

<?xml version='1.0'? >
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:fo="http://www.w3.org/1999/XSL/Format"
    version='1.0'>

    <xsl:template match="states">
        <fo:root>

            <fo:layout-master-set>
                 <fo:simple-page-master master-name="mainPage"
                     page-height="300mm" page-width="200mm"
                     margin-top="20mm" margin-bottom="20mm"
                     margin-left="20mm" margin-right="20mm">

                     <fo:region-body
                       margin-top="0mm" margin-bottom="10mm"
                       margin-left="0mm" margin-right="0mm"/>

                     <fo:region-after extent="20mm"/>
                 </fo:simple-page-master>
             </fo:layout-master-set>

             <fo:page-sequence master-reference="mainPage">
                 .
                 .
                 .

The next step is to specify the content of the page sequence, and you do that with the <fo:flow> element, as described in the next section.

Using <fo:flow>

You use <fo:flow> to create a text flow, much like the flow in browsers, where the browser decides how to arrange elements. To create a flow, you specify a region, and the document content flows into that region.

You don't need to let text flow as the XSL-FO processor chooses. Besides <fo:flow>, you can also use <fo:static-content> in page sequences. The content in <fo:static-content> is static, which means it stays as you've arranged it. Static content is often used for headers and footers, where you want to dictate the text content and position, such as page numbers that you might always want centered or on the right.

The <fo:flow> element supports a property named flow-name, and you can use that property to indicate that you want text content to flow into the body region of pages like this, finishing off the <fo:root> element:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:fo="http://www.w3.org/1999/XSL/Format"
    version='1.0'>

    <xsl:template match="states">
        <fo:root>
            .
            .
            .
             <fo:page-sequence master-reference="mainPage">
                 <fo:flow  flow-name="xsl-region-body">

                        <xsl:apply-templates/>

                    </fo:flow>
             </fo:page-sequence>

        </fo:root>
    </xsl:template>
    .
    .
    .

Note that the <fo:flow> element, which handles the XML document's content, has an <xsl:apply-templates/> element in it. This means that the XML elements in the XML document will be matched with templates in the XSLT style sheet. For example, to match the <name> elements, you use this template:

<xsl:template match="state/name">
        .
        .
        .

Now you've matched a <name> element. You want to display its text in bold, underlined text, as shown in Figure 10.1. How do you do that? You start by using <fo:block> to create a block element.

Using <fo:block>

In XSL-FO you can use the <fo:block> element to create block-level elements, much like the ones you created on Day 6, when working with CSS. You use this element to create your own rectangular region that appears on its own line. You can use it to give each data item from ch10_01.xml its own line in the output document.

You can use these properties with <fo:block> elements:

• Accessibility properties: source-document and role
• Aural properties: azimuth, cue-after, cue-before, elevation, pause-after, pause-before, pitch, pitch-range, play-during, richness, speak, speak-header, speak-numeral, speak-punctuation, speech-rate, stress, voice-family, and volume
• Border, padding, and background properties: background-attachment, background-color, background-image, background-repeat, background-position-horizontal, background-position-vertical, border-before-color, border-before-style, border-before-width, border-after-color, border-after-style, border-after-width, border-start-color, border-start-style, border-start-width, border-end-color, border-end-style, border-end-width, border-top-color, border-top-style, border-top-width, border-bottom-color, border-bottom-style, border-bottom-width, border-left-color, border-left-style, border-left-width, border-right-color, border-right-style, border-right-width, padding-before, padding-after, padding-start, padding-end, padding-top, padding-bottom, padding-left, and padding-right
• Font properties: font-family, font-size, font-stretch, font-size-adjust, font-style, font-variant, and font-weight
• Hyphenation properties: country, language, script, hyphenate, hyphenation-character, hyphenation-push-character-count, and hyphenation-remain-character-count
• Block margin properties: margin-top, margin-bottom, margin-left, margin-right, space-before, space-after, start-indent, and end-indent
• break-after
• break-before
• color
• font-height-override-after
• font-height-override-before
• hyphenation-keep
• hyphenation-ladder-count
• id
• keep-together
• keep-with-next
• keep-with-previous
• last-line-end-indent
• linefeed-treatment
• line-height
• line-height-shift-adjustment
• line-stacking-strategy
• orphans
• relative-position
• space-treatment
• span
• text-align
• text-align-last
• text-indent
• visibility
• white-space-collapse
• widows
• wrap-option
• z-index

To handle the data in the <name>, <population>, <capital>, and other elements in the XML document, you can use the following templates in ch10_02.xsl, which uses <fo:block> to create blocks displaying that data:

<xsl:template match="state/name">
    <fo:block font-weight="bold" font-size="18pt"
        line-height="24pt" font-family="sans-serif"
        text-decoration="underline">
        Name:
        <xsl:value-of select="."/>
    </fo:block>
</xsl:template>

<xsl:template match="state/population">
    <fo:block font-size="18pt" line-height="24pt"
        font-family="sans-serif">
        Population (people):
        <xsl:value-of select="."/>
    </fo:block>
</xsl:template>

<xsl:template match="state/capital">
    <fo:block font-size="18pt" line-height="24pt"
        font-family="sans-serif">
        Capital:
        <xsl:value-of select="."/>
    </fo:block>
</xsl:template>

<xsl:template match="state/bird">
    <fo:block font-size="18pt" line-height="24pt"
        font-family="sans-serif">
        Bird:
        <xsl:value-of select="."/>
    </fo:block>
</xsl:template>

<xsl:template match="state/flower">
    <fo:block font-size="18pt" line-height="24pt" font-family="sans-serif">
        Flower:
        <xsl:value-of select="."/>
    </fo:block>
</xsl:template>

<xsl:template match="state/area">
    <fo:block font-size="18pt" line-height="24pt" font-family="sans-serif">
        Area (square miles):
        <xsl:value-of select="."/>
    </fo:block>
</xsl:template>

Now you have created the XSLT style sheet, ch10_02.xsl, which converts ch10_01.xml into the XSL-FO document ch10_03.fo. Congratulations! You've created an XSLT style sheet that transforms an XML document into XSL-FO form, which the FOP XSL-FO processor can now translate into a PDF file.