The XSL-FO Formatting Objects

In XSLT documents, you use elements such as <xsl:stylesheet> , <xsl:output> , and so on:

 <?xml version="1.0" encoding="UTF-8"?>  <xsl:stylesheet version="1.0"  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">      <xsl:output method="xml"/>      <xsl:template match="*">          <xsl:copy>              <xsl:apply-templates/>              .              .              .

An XSL-FO document is written in much the same way, but rather than use XSLT elements such as <xsl:stylesheet> , you use elements based on the XSL-FO formatting objects. There are 56 such formatting objects, such as the root object, which creates the root node of an XSL-FO document, or the block object, which creates a block region (a rectangular display area, much like the one an <H1> header creates in an HTML document).

XSL formatting objects have their own namespace, http://www.w3.org/ 1999/XSL/Format, and the namespace prefix people use for that namespace is almost invariably fo , for formatting objects. (This convention was adopted because thats the namespace prefix used in the XSL specification.) To write XSL-FO documents, you use elements that correspond to the various XSL-FO objects, such as <fo:root> for the root element, <fo:block> to create a display block, and so on. For example, heres how you might start an XSL-FO documentnote that I declare the fo namespace prefix to correspond to the XSL-FO namespace:

 <?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="page">              <fo:region-body margin-right="0mm" margin-left="0mm"                  margin-bottom="10mm" margin-top="0mm"/>          .          .          .

Note that XSL-FO documents are XML documents, which means you can use standard XML comments,  , throughout. Note also that the elements <fo:simple-pagemaster> and <fo:regionbody> have attributes such as margin-right and page-height . These attributes are called properties in XSL-FO, and there are a lot of themabout 240 as of this writing. For example, heres how I can create an XSL-FO blocka rectangular display areathat displays the text Welcome to XSL formatting in 36 point sansserif font. I use the <fo:block> formatting object and the XSL-FO properties font-family , line-height (which specifies the height of the block), and font- size as follows :

 <fo:block font-family="sans-serif" line-height="48pt" font-size="36pt">      Welcome to XSL formatting  </fo:block>

In this section, Ill take a look at the XSL-FO objects, and in the next section, the XSL-FO properties that you can use with them. Using XSL-FO objects and properties, you can create XSL-FO documents, which are usually given the extension .fo. When you pass these documents to fop, it converts the document to .pdf format.

You can find all the XSL-FO formatting objects at www.w3.org/TR/xsl/slice6.html, along with a description of each. The following objects exist as of this writing, and youll see many of them in action in this and the next chapter:

<fo: bidi-override >. Overrides the default Unicode- bidirectionality algorithm direction. (This algorithm is used in mixed-language documents.)
<fo:block>. Creates a display block, which is used for creating rectangular regions , such as youd use for paragraphs, titles, headlines, figure and table captions, and so on.
<fo:block-container>. Creates a container for blocks, which you can then position as you like in a document.
<fo:character>. Represents a single character.
<fo: color -profile>. Creates a color profile for a stylesheet, which you can then use with color functions (see /TR/xsl/slice5.html#expr-color-functions for more details).
<fo:conditional-page-master-reference>. Specifies a page-master to be used when specified conditions are met.
<fo:declarations>. Creates global declarations.
<fo:external-graphic>. Adds a graphic to a document. (The graphics data resides outside the result document, but can be incorporated into PDF documents by processors like fop.)
<fo:float>. Specifies that some content is formatted in a separate, floating area at the beginning of the page or placed to one side.
<fo:flow>. Handles the text flow that is displayed in a document. Blocks an inline areas flow as theyre placed in a document.
<fo:footnote>. Specifies a footnote citation as well as the associated footnote.
<fo:footnote-body>. Specifies the content of the footnote.
<fo: initial-property-set >. Specifies the formatting properties for the initial line of a block.
<fo:inline>. Creates an inline area. Inline areas are often used to format a specific part of the text in a block.
<fo:inline-container>. Creates a container for inline objects, enabling you to handle them together.
<fo:instream-foreign-object>. Used to insert an inline graphic or other object into a document.
<fo:layout-master-set>. Specifies a wrapper for all the masters used in the document.
<fo:leader>. Creates a row of a repeating character or pattern of characters that is used to separate two text formatting objects.
<fo: list-block >. Creates a formatted list of the kind youll see in the next chapter.
<fo:list-item>. Specifies the label and the body of an item in a list.
<fo:list-item-body>. Specifies the content of the body of an item in a list.
<fo:list-item-label>. Specifies the content of the label of an item in a list.
<fo:marker>. Used with <fo:retrieve-marker> to create headers or footers on the fly.
<fo:multi-case>. Specifies objects that the parent <fo: multi-switch > can show or hide.
<fo: multi-properties >. Enables you to switch between two or more property sets.
<fo:multi-property-set>. Specifies an alternative set of properties.
<fo:multi-switch>. Switches between two or more sub-trees of formatting objects.
<fo:multi-toggle>. Used inside an <fo:multi-case> element to switch to another <fo:multicase> .
<fo: page-number >. Indicates the current page number.
<fo:page-number-citation>. References the page number for the page containing a given formatting object.
<fo:page-sequence>. Specifies how to create a sequence of pages within a document.
<fo:page-sequence-master>. Contains sequences of page masters that are used to generate sequences of pages.
<fo:region-after>. Indicates the region located after an <fo:region-body> region.
<fo:region-before>. Indicates the region before a <fo:region-body> region.
<fo:region-body>. Indicates the region in the center of an <fo:simple-page-master> .
<fo:region-end>. Indicates the region at the end of a <fo:region-body> region.
<fo:region-start>. Indicates the region starting a <fo:region-body> region.
<fo:repeatable-page-master-alternatives>. Specifies repeated instances of a set of alternative page masters.
<fo:repeatable-page-master-reference>. Indicates a sub-sequence of repeated instances of a single page-master.
<fo:retrieve-marker>. Used with <fo:marker> to create headers or footers on the fly.
<fo:root>. The document node of an XSL-formatted document.
<fo:simple-link>. Specifies the start location in a simple link.
<fo:simple-page-master>. Specifies the geometry of a page, which may be divided into up to five regions.
<fo: single-page -master-reference>. Indicates a sub-sequence made up of a single instance of a single page-master.
<fo:static-content>. Contains a sequence of formatting objects to be displayed in one region or repeated in regions on one or more pages in a page sequence. Most often used for repeating headers and footers.
<fo:table>. Creates a table. Encloses elements such as <fo:table-column> and <fo:table-body> .
<fo:table-and-caption>. Encloses the data and caption of a table.
<fo:table-body>. Specifies the content of the table body. Encloses elements such as <fo:table-row>.
<fo:table-caption>. Specifies block-level formatting objects, which hold the caption for a table.
<fo:table- cell >. Places data in table cells .
<fo:table-column>. Specifies characteristics for table cells that have the same column.
<fo:table-footer>. Specifies the content of the table footer.
<fo:table-header>. Specifies the content of the table header.
<fo:table-row>. Connects table cells into rows. Contains <fo:table-cell> elements.
<fo:title>. Specifies the title of a document.
<fo:wrapper>. Specifies properties for a group of formatting objects.

Each of these elements also supports one or more XSL-FO formatting properties .