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.