How to Publish XML Documents in HTML and PDF

This How-To shows you how to publish XML documents in HTML and PDF using Cocoon. It requires no prior knowledge of Cocoon, XSLT or XSL-FO.

You will learn how to build a simple pipeline that converts XML documents on-the-fly to HTML or PDF using simple XSLT transforms. This is similar to the hello.html and hello.pdf samples of the standard Cocoon installation. However, this How-To teaches you how to build these mechanisms yourself. Thus, you will get a better feel of how Cocoon publishing really works.

Beginning Cocoon users who want to learn how to publish HTML and/or PDF documents from XML data.

You will not need a fancy XML editor for this How-To. Copying and pasting the sample code snippets into any text editor will do.

Under webapps/cocoon/mount, create a new directory and name it html-pdf. All files used by this How-To will reside in this directory.

After a browser refresh, http://localhost:8080/cocoon/mount/ should display the name of this new directory, among others.

To keep it simple we will use two small XML files as our data sources. Later, you will probably use additional data sources like live XML feeds, databases, and others.

In the html-pdf directory, create the following two files, and name them exactly as shown.

Be careful about the use of lower/uppercase in filenames if you're working on a Unix or Linux system. On such systems, thisFile.xml is not the same as Thisfile.xml.

To avoid any errors, use copy/paste when creating XML documents from examples on this page.

Do not leave spaces at the start of XML files. The <?xml... processing instruction must be the first character in the file.

The most common way of producing HTML in Cocoon is to use XSLT transforms to select and convert the appropriate elements of the input documents.

Copy the file shown below to the html-pdf directory alongside your XML documents, naming it doc2html.xsl

<?xml version="1.0" encoding="iso-8859-1"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">

<!-- generate HTML skeleton on root element -->
<xsl:template match="/">
  <html>
    <head>
      <title><xsl:apply-templates select="page/title"/></title>
    </head>
    <body>
        <xsl:apply-templates/>
    </body>
  </html>
</xsl:template>

<!-- story is used later by the Meerkat example -->
<xsl:template match="p|story">
    <p><xsl:apply-templates/></p>
</xsl:template>

<!-- convert sections to HTML headings -->
<xsl:template match="s1">
    <h1><xsl:apply-templates select="@title"/></h1>
    <xsl:apply-templates/>
</xsl:template>

</xsl:stylesheet>

Basically what this does is generate an HTML skeleton and convert the input markup to HTML. We won't go into details here. Rather, our goal is to show you how the components of the publishing chain are combined.

We now have documents to publish and an XSLT transform to convert them to our HTML output format. What's left is to connect them in a processing pipeline. Then, the sitemap can select the pipeline based on the details of the browser request.

To tell Cocoon how to process requests made to html-pdf, copy the following snippet to a file named sitemap.xmap in the html-pdf subdirectory.

<?xml version="1.0" encoding="iso-8859-1"?>
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">

    <!-- use the standard components -->
    <map:components>
        <map:generators default="file"/>
        <map:transformers default="xslt"/>
        <map:readers default="resource"/>
        <map:serializers default="html"/>
        <map:selectors default="browser"/>
        <map:matchers default="wildcard"/>
    </map:components>
      
    <map:pipelines>
        <map:pipeline>
            <!-- respond to *.html requests with 
                 our docs processed by doc2html.xsl -->
            <map:match pattern="*.html">
                <map:generate src="{1}.xml"/>
                <map:transform src="doc2html.xsl"/>
                <map:serialize type="html"/>
            </map:match>
            
            <!-- later, respond to *.pdf requests with 
                 our docs processed by doc2pdf.xsl -->
            <map:match pattern="*.pdf">
                <map:generate src="{1}.xml"/>
                <map:transform src="doc2pdf.xsl"/>
                <map:serialize type="fo2pdf"/>
            </map:match>
        </map:pipeline>
    </map:pipelines>
</map:sitemap>

The important thing here is the first map:match element, which tells Cocoon how to process requests ending in *.html in this directory. Again, we won't go into details here, but that's where it happens.

The above sitemap is already configured for PDF publishing. However, this capability is not fully functional at this time because we haven't created the required XSLT transform yet.

If this doesn't work, you might want to double check the above steps first, and then look at the Cocoon logs in the webapps/cocoon/WEB-INF/logs directory. You will find lots of information there. Look for clues in files that change in size when the error happens.

PDF documents are created via XSL-FO documents which are XML documents that use a specific page-description vocabulary. (See References below for more info). The actual conversion to PDF is done by the PdfSerializer which uses software from FOP, another Apache Software Foundation project.

To activate the PDF conversion, copy the code snippet shown below to the html-pdf directory along with your XML documents, and name it doc2pdf.xsl

<?xml version="1.0" encoding="iso-8859-1"?>
<xsl:stylesheet 
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
    xmlns:fo="http://www.w3.org/1999/XSL/Format"
>
    <!-- generate PDF page structure -->
    <xsl:template match="/">
        <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
            <fo:layout-master-set>
                <fo:simple-page-master master-name="page"
                  page-height="29.7cm" 
                  page-width="21cm"
                  margin-top="1cm" 
                  margin-bottom="2cm" 
                  margin-left="2.5cm" 
                  margin-right="2.5cm"
                >
                    <fo:region-before extent="3cm"/>
                    <fo:region-body margin-top="3cm"/>
                    <fo:region-after extent="1.5cm"/>
                </fo:simple-page-master>

                <fo:page-sequence-master master-name="all">
                    <fo:repeatable-page-master-alternatives>
                        <fo:conditional-page-master-reference 
                           master-reference="page" page-position="first"/>
                    </fo:repeatable-page-master-alternatives>
                </fo:page-sequence-master>
            </fo:layout-master-set>

            <fo:page-sequence master-reference="all">
                <fo:flow flow-name="xsl-region-body">
                    <fo:block><xsl:apply-templates/></fo:block>
                </fo:flow>
            </fo:page-sequence>
        </fo:root>
    </xsl:template>

    <!-- process paragraphs -->
    <xsl:template match="p">
        <fo:block><xsl:apply-templates/></fo:block>
    </xsl:template>

    <!-- convert sections to XSL-FO headings -->
    <xsl:template match="s1">
        <fo:block font-size="24pt" color="red" font-weight="bold">
            <xsl:apply-templates select="@title"/>
        </fo:block>
        <xsl:apply-templates/>
    </xsl:template>

</xsl:stylesheet>

This file is already referenced by the sitemap we created, so no additional configuration is needed.

At this point you should be able to display the results in PDF in addition to the existing HTML versions:

I hope you're beginning to see that publishing PDF and HTML documents in Cocoon is not too complicated, once you know what goes where.

The nice thing is that all of our huge corpus of XML documents (actually, only two documents right now, but that's a start... ) is processed by just two XSLT files, one for each target format.

If you need to change the appearance of the published documents, you have to change only these two XSLT transforms. There's no need to touch the source documents.

Using dynamic XML as the data source is very easy because the Cocoon FileGenerator can read URLs as well.

If you add the map:match element shown in bold below before the existing map:match elements in your sitemap.xmap file, requesting http://localhost:8080/cocoon/mount/html-pdf/meerkat.html should display real-time news from Meerkat (assuming an Internet connection to Meerkat is available).

The news will be displayed in a very rough format. However, this can be improved by writing a specific XSLT transform for this Meerkat data and using it, instead of doc2html.xsl, in the meerkat.html pipeline.


...
<map:pipeline>



<map:match pattern="meerkat.html">
    <map:generate src="http://www.oreillynet.com/meerkat/?_fl=xml"/>
    <map:transform src="doc2html.xsl"/>
    <map:serialize type="html"/>
</map:match>



<map:match pattern="*.html">
etc...

When you are generating multiple formats from a single data source, it is often a good idea to generate an intermediate logical document that describes the output in a format-neutral way.

This is obviously not needed in our simple example. If you're aiming for more complicated publishing tasks, then you might want to read about this "publishing pattern" in Martin Fowler's Two Step View article.

To go further, you will need to learn about the following technologies and tools.

Care to comment on this How-To? Got another tip? Help keep this How-To relevant by passing along any useful feedback to the author, Bertrand Delacrétaz.