Directive example

A full example for a custom directive, where we want to embed real world addresses into our RST document and maintain the semantics in the resulting docbook, could look like:

Address example
===============

.. address:: John Doe
    :street: Some Lane 42

We would possibly add more information, like the ZIP code, city and state, but skip this to keep the code short. The implemented directive then would just need to take these information and transform it into valid docbook XML using the DOM extension.

1. <?php
2. class myAddressDirective extends ezcDocumentRstDirective
3. {
4. public function toDocbook( DOMDocument $document, DOMElement $root )
5. {
6. $address = $document->createElement( 'address' );
7. $root->appendChild( $address );
9. if ( !empty( $this->node->parameters ) )
10. {
11. $name = $document->createElement( 'personname', htmlentities( $this->node->parameters ) );
12. $address->appendChild( $name );
13. }
15. if ( isset( $this->node->options['street'] ) )
16. {
17. $street = $document->createElement( 'street', htmlentities( $this->node->options['street'] ) );
18. $address->appendChild( $street );
19. }
20. }
21. }
22. ?>

The AST node, which should be rendered, is passed to the constructor of the custom directive visitor and available in the class property $node. The complete DOMDocument and the current DOMNode are passed to the method. In this case we just create a address node with the optional child nodes street and personname, depending on the existence of the respective values.

You can now render the RST document after you registered you custom directive handler as shown above:

1. <?php
3. require 'tutorial_autoload.php';
5. // Load custom directive
6. require '00_01_address_directive.php';
8. $document = new ezcDocumentRst();
9. $document->registerDirective( 'address', 'myAddressDirective' );
10. $document->loadString( <<<EORST
11. Address example
12. ===============
14. .. address:: John Doe
15. :street: Some Lane 42
16. EORST
17. );
19. $docbook = $document->getAsDocbook();
20. echo $docbook->save();
21. ?>

The output will then look like:

<?xml version="1.0"?>
<article xmlns="http://docbook.org/ns/docbook">
  <section id="address_example">
    <sectioninfo/>
    <title>Address example</title>
    <address>
      <personname> John Doe</personname>
      <street> Some Lane 42</street>
    </address>
  </section>
</article>

Modification of XHTML rendering

You can modify the generated output of the XHTML visitor by creating a custom visitor for the RST AST. The easiest way probably is to extend from one of the existing XHTML visitors and reusing it. For example you may want to fill the type attribute in bullet lists, like known from HTML, which isn't valid XHTML, though:

class myDocumentRstXhtmlVisitor extends ezcDocumentRstXhtmlVisitor
{
    protected function visitBulletList( DOMNode $root, ezcDocumentRstNode $node )
    {
        $list = $this->document->createElement( 'ul' );
        $root->appendChild( $list );

        $listTypes = array(
            '*'            => 'circle',
            '+'            => 'disc',
            '-'            => 'square',
            "\xe2\x80\xa2" => 'disc',
            "\xe2\x80\xa3" => 'circle',
            "\xe2\x81\x83" => 'square',
        );
        // Not allowed in XHTML strict
        $list->setAttribute( 'type', $listTypes[$node->token->content] );

        // Decoratre blockquote contents
        foreach ( $node->nodes as $child )
        {
            $this->visitNode( $list, $child );
        }
    }
}

The structure, which is not enforced for visitors, but used in the docbook and XHTML visitors, is to call special methods for each node type in the AST to decorate the AST recursively. This method will be called for all bullet list nodes in the AST which contain the actual list items. As the first parameter the current position in the XHTML DOM tree is also provided to the method.

To create the XHTML we can now just create a new list node (<ul>) in the current DOMNode, set the new attribute, and recursively decorate all descendants using the general visitor dispatching method visitNode() for all children in the AST. For the AST children being also rendered as children in the XML tree, we pass the just created DOMNode (<ul>) as the new root node to the visitNode() method.

After defining such a class, you could use the custom visitor like shown above:

1. <?php
2. $document = new ezcDocumentRst();
3. $document->options->xhtmlVisitor = 'myDocumentRstXhtmlVisitor';
4. $document->loadFile( $from );
6. $xhtml = $document->getAsXhtml();
7. $xml = $xhtml->save();
8. ?>

Now the lists in the generated XHTML will also the type attribute set.

Extending RST writing

As said before, not all existing docbook elements might already be handled by the converter. But its handler based mechanism makes it easy to extend or overwrite existing behaviour.

Similar to the example above we can convert the <address> docbook element back to the address RST directive.

1. <?php
3. require 'tutorial_autoload.php';
5. $docbook = new ezcDocumentDocbook();
6. $docbook->loadFile( 'address.xml' );
8. class myAddressElementHandler extends ezcDocumentDocbookToRstBaseHandler
9. {
10. public function handle( ezcDocumentElementVisitorConverter $converter, DOMElement $node, $root )
11. {
12. $root .= $this->renderDirective( 'address', $node->textContent, array() );
13. return $root;
14. }
15. }
17. $converter = new ezcDocumentDocbookToRstConverter();
18. $converter->setElementHandler( 'docbook', 'address', new myAddressElementHandler() );
20. $rst = $converter->convert( $docbook );
21. echo $rst->save();
23. ?>

The handler classes are assigned to XML elements in some namespace, "docbook" in this case. It is registered in line 18 for the element "address". The class itself has to extend from the ezcDocumentElementVisitorHandler class, which is in this case already extended by ezcDocumentDocbookToRstBaseHandler, which provides some convenience methods for RST creation, like renderDirective() used in this example.

The handler is called, whenever the element, it has been registered for, occurs in the docbook XML tree. In this case it has to append the generated RST part for this element to the RST document - and may call the general conversion handler again for its child elements. This example converts the above shown docbook XML back to:

.. _address_example:

===============
Address example
===============

.. address::
       John Doe
       Some Lane 42

Which ignores any special address sub elements for the simplicity of the example. For more examples on element handlers check the existing implementations.

Link handling

Inside eZ XML documents link URIs are replaced with IDs, which reference the links inside the eZ Publish database, to ensure that a changed link is update globally. The replacing of such links is handled by a class extending from ezcDocumentEzXmlLinkProvider. By default dummy URLs are added to the documents.

URLs are either referenced directly by their ID, a node ID, or an object ID. Those parameters are passed to the link provide, which then should return an URL for that.

1. <?php
3. require 'tutorial_autoload.php';
5. class myLinkProvider extends ezcDocumentEzXmlLinkProvider
6. {
7. public function fetchUrlById( $id, $view, $show_path )
8. {
9. return 'http://host/path/' . $id;
10. }
12. public function fetchUrlByNodeId( $id, $view, $show_path ) {}
13. public function fetchUrlByObjectId( $id, $view, $show_path ) {}
14. }
16. $document = new ezcDocumentEzXml();
17. $document->loadString( '<?xml version="1.0"?>
18. <section xmlns="http://ez.no/namespaces/ezpublish3">
19. <header>Paragraph</header>
20. <paragraph>Some content, with a <link url_id="1">link</link>.</paragraph>
21. </section>' );
23. // Set link provider
24. $converter = new ezcDocumentEzXmlToDocbookConverter();
25. $converter->options->linkProvider = new myLinkProvider();
27. $docbook = $converter->convert( $document );
28. echo $docbook->save();
29. ?>

The link provider is only implemented as a trivial stub, but you can establish a database connection there and actually fetch the required data. I this case the generated docbook document look like:

<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<article xmlns="http://docbook.org/ns/docbook">
  <section>
    <title>Paragraph</title>
    <para>Some content, with a <ulink url="http://host/path/1">link</ulink>.</para>
  </section>
</article>

The link provider is set again as a option of the converter. Like shown for the docbook conversions of the other handlers, you can register element handlers for yet unhandled eZ XML elements on the converter, too.

Output writers

Since there are numerous different PDF renderers in the PHP world and the available ones might depend on the current environment, the document component supports different PDF driver, as wrapper around different existent libraries.

For now two implementation exist for pecl/har and TCPDF, but it is fairly easy to write another one, for another PDF class.

pear install pecl/haru

$pdf = new ezcDocumentPdf();
$pdf->options->driver = new ezcDocumentPdfHaruDriver();

$pdf = new ezcDocumentPdf();
$pdf->options->driver = new ezcDocumentPdfTcpdfDriver();

Styling the PDF

The PDF output can be styled using a CSS like language, which assigns styles based on the Docbook XML structure. The default styling rules are defined in the default.css.

The first most relevant part are the general layout options, which can be defined for the common article root node in the Docbook XML file. You can set global font options there, like:

article {
    // Basic font style definitions
    font-size:   "12pt";
    font-family: "serif";
    font-weight: "normal";
    font-style:  "normal";
    line-height: "1.4";
    text-align:  "left";

    // Basic page layout definitions
    text-columns: "1";
    text-column-spacing: "10mm";

    // General text layout options
    orphans: "3";
    widows:  "3";
}

The meaning of the first set of options should be obvious from CSS. We require each value to be wrapped by quotes for easier parsing, though.

The second set of options defines options for multi-column layouts, which are not available in the web, but quite common in generated PDF documents. You can specify the number of text columns, as well as the distance between the text columns here.

The third set in this example defines lesser known text layout options like the handling of orphans and widows, which specify the handling of overlapping parts of paragraphs on page wrapping.

You can, of course, apply those styles to any elements in your document, using the common CSS addressing rules, like:

// Emphasis node anywhere in the document
emphasis { ... }

// Title element directly below a section element
section > title { ... }

// Title element anywhere below a section element
section title { ... }

// Title element with the ID "first_title"
title#first_title { ... }

// Title element with the class "foo"
title.foo { ... }

// emphasis node directly below a title with class "foo", anywhere in a
// section with the ID "first"
section#first title.foo > emphasis { ... }

The values and measures for the properties are very similar to the properties in CSS. For example the margin and padding properties accept one- to four-tuples of values, with the same respective meaning like in CSS.

Another central formatting element, which is special to the PDF generation, is the virtual element "page":

page {
    page-size: "A4";
    page-orientation: "portrait";
    padding: "22mm 16mm";
}

The page-size property accepts several known page size identifiers and the page-orientation defines the orientation of a page. You can also address any page directly by its ID, which will be 'page_1' for the first page, or its class, which will be "right", or "left", depending on the current page number.

A detailed description of all available PDF style options is available here.

para {
    // Top margin: 12 mm; Right margin: .1 inch; Bottom margin: 10 points,
    // Left margin: 1 pixel
    margin: "12 .1in 10pt 1px";
}

PDF parts

PDF parts are additional parts in a rendered document, like headers and footers. You can implement and register them yourself, and they are activated by different triggers, like:

• on document creation
• on page creation
• when a document has been finished

The default implementation for headers and footers is triggered on page creation and renders the title of the document, its author and a page number in the header or the footer. To develop a custom PDF part you should extend from the ezcDocumentPdfPart class.

For the following document we are using a set of custom styles, as well as a header and a footer to customize the rendered PDF document. The additional custom CSS changes the default font and the page border:

article {
    font-family: "sans-serif";
    font-size: "10pt";
}

page {
    padding: "15mm 30mm";
}

The code using the custom CSS and headers and footers then looks like:

1. <?php
3. require 'tutorial_autoload.php';
5. // Convert some input RSTfile to docbook
6. $document = new ezcDocumentRst();
7. $document->loadFile( './article/introduction.txt' );
9. // Load the docbook document and create a PDF from it
10. $pdf = new ezcDocumentPdf();
11. $pdf->options->errorReporting = E_PARSE | E_ERROR | E_WARNING;
13. // Load a custom style sheet
14. $pdf->loadStyles( 'custom.css' );
16. // Add a customized footer
17. $pdf->registerPdfPart( new ezcDocumentPdfFooterPdfPart(
18. new ezcDocumentPdfFooterOptions( array(
19. 'showDocumentTitle' => false,
20. 'showDocumentAuthor' => false,
21. 'height' => '10mm',
22. ) )
23. ) );
25. // Add a customized header
26. $pdf->registerPdfPart( new ezcDocumentPdfHeaderPdfPart(
27. new ezcDocumentPdfFooterOptions( array(
28. 'showPageNumber' => false,
29. 'height' => '10mm',
30. ) )
31. ) );
33. $pdf->createFromDocbook( $document->getAsDocbook() );
34. file_put_contents( __FILE__ . '.pdf', $pdf );
36. ?>

The first part, the creation of a Docbook document from a RST document is just the same like in the first example.

Afterwards we load the above mentioned custom.css as an additional style. You can load as many styles as you want. If multiple styles are loaded, the latter ones always (partly) redefine the first styles.

After that two custom PDF parts are registered using their respective option class to configure their skin. The footer should only show the page number, while the header should display all parts (title and author), but the page number.

At the end of the example the document is created as usual, and looks like this: 04_02_create_pdf_styled.pdf Since the source document does not include any author information, this information is also not rendered in the header.

Hyphenating

Proper hyphenation is crucial for nice text rendering especially for justified paragraph formatting. Since hyphenation is highly language dependent you can create and use your own custom hyphenator - the default one doesn't do any hyphenation by default, but just keeps every word as it is.

Custom hyphenators can be implemented by extending from the abstract class ezcDocumentPdfHyphenator. The only need to implement one Method, `splitWord()`, which should return possible splitting points of the given word, as documented in the ezcDocumentPdfHyphenator class.

The custom hyphenator can be configured in the ezcDocumentPdfOptions class, like this:

$pdf = new ezcDocumentPdf();
$pdf->options->hyphenator = new myHyphenator();

The hyphenator will then be used by all text renderers during the rendering process.