Next / Previous / Contents / Shipman's homepage

4. Interface to the fohelpers module

Module fohelpers.py contains various classes to assist in the creation of XSL-FO documents.

Because an XSL-FO file is an XML document, we will use the etbuilder module described in Python XML processing with lxml, which is well-suited for building an XML document from scratch.

Because most of the code revolves around building the XML file, a number of the functions provided by the current package take as arguments XML element nodes represented by instances of the et.Element class from the etbuilder module (which in other Python-XML interfaces are instances of class etree.Element). In most cases these arguments can be generated by the E() universal node-builder object from that module.

Here is the general procedure for creating a document as an XSL-FO file.

  1. To create the root output XSL-FO document, use the constructor for Section 8, “class FlowTree: The entire document”. As built, this class holds the et.ElementTree instance representing the document, with the proper root element (whose name is root, strangely enough), and its required layout-master-set child node attached. These nodes are exported as the .root and .masters attribute, respectively.

  2. To the .masters node, add child nodes describing your various page layouts and when to use which one.

  3. To the .root node in the FlowTree instance, add one or more page-sequence subtrees representing the actual content of your document, using Section 20, “pageSequence(): Generate a page-sequence element”.

  4. To that page-sequence subtree, add static content (e.g., running heads) using Section 21, “staticContent(): Generate a static-content element”.

  5. Also the page-sequence subtree, add a flow element using Section 22, “flow(): Create a flow element”.

  6. Add your content as children of the flow element. To add a block element, use Section 23, “block(): Generate a block element”. To add inline markup inside a block element, see Section 24, “inline(): Generate an inline element”.

You may find all this clearer if you review pp. 30–63 of the Pawson book referenced in Section 1, “Direct construction of PDF files from Python”. You may also get the general idea by examining our small test example, Section 29, “fohelptest: Test driver for fohelpers.

In addition, there are several other classes and utility functions that you will likely need.