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.
</p>
<p>
It has been updated for Cocoon 2.1, which does not require the use of the <em>mount</em> directory anymore.
</p>
</s1>
<s1 title="Purpose">
<p>
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 <code>hello.html</code> and <code>hello.pdf</code> 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.
</p>
</s1>
<s1 title="Intended Audience">
<p>
Beginning Cocoon users who want to learn how to publish HTML and/or PDF documents from XML data.
</p>
</s1>
<s1 title="Prerequisites">
<p>Here's what you need:</p>
<ul>
<li>Cocoon must be running on your system. The steps below have been tested with Cocoon 2.1m3-dev, but they should work with any 2.1 version.</li>
<li>This document assumes a standard installation where Cocoon is started by the <em>cocoon.sh</em> (or cocoon.bat) script and where
<code>http://localhost:8888/</code> points to the <em>Welcome to Apache Cocoon</em> page.
<br />
If your installation runs on a different URL, you will have to adjust
the URLs provided throughout this How-To as necessary.
</li>
<li>You must be able to create and edit XML files in the main directory of the Cocoon installation.
When started from cocoon.sh, this directory is <code>build/webapp</code> under the directory that contains cocoon.sh.
</li>
</ul>
<note>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.</note>
<note>
Running "build clean" deletes everything under build/webapp, make sure to save your example files if you
need to do a clean build.
</note>
</s1>
<s1 title="Steps">
<p>
Here's how to proceed.
</p>
<s2 title="1. Create the work directory" >
<p>
Under <code>build/webapp</code>, create a new directory and name it <code>html-pdf</code>.
All files used by this How-To will reside in this directory.
</p>
<p>
At this point, <code>http://localhost:8888/html-pdf/</code> should display an error page saying <em>Resource not found</em>,
indicating that the file <em>build/webapp/html-pdf/sitemap.xmap</em> was not found. This is normal, as the newly
created directory does not yet contain the required sitemap file.
</p>
</s2>
<s2 title="2. Create the XML example documents" >
<p>
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.</p>
<p>
In the <code>html-pdf</code> directory, create the following two files, and name them exactly as
shown.
</p>
<p>
Contents of file <strong>pageOne.xml</strong>:
</p>
<source><![CDATA[
<?xml version="1.0" encoding="iso-8859-1"?>
<page>
<title>This is the pageOne.xml example</title>
<s1 title="Section one">
<p>This is the text of section one</p>
</s1>
</page>
]]></source>
<p>
Contents of file <strong>pageTwo.xml</strong>:
</p>
<source><![CDATA[
<?xml version="1.0" encoding="iso-8859-1"?>
<page>
<title>This is the pageTwo.xml example</title>
<s1 title="Yes, it works">
<p>Now you're hopefully seeing pageTwo in HTML or PDF</p>
</s1>
</page>
]]></source>
<note>
Be careful about the use of lower/uppercase in filenames if you're working on a Unix or Linux system.
On such systems, <code>thisFile.xml</code> is not the same as <code>Thisfile.xml</code>.
</note>
<note>
To avoid any errors, use copy/paste when creating XML documents from examples on this page.
</note>
<note>
Do not leave spaces at the start of XML files. The <?xml... processing instruction must
be the first character in the file.
</note>
</s2>
<s2 title="3. Create the XSLT transform for HTML" >
<p>
The most common way of producing HTML in Cocoon is to use <strong>XSLT transforms</strong> to select and convert
the appropriate elements of the input documents.
</p>
<p>
Copy the file shown below to the <code>html-pdf</code> directory alongside your XML documents, naming it
<!-- 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>
]]></source>
<note>
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.
</note>
</s2>
<s2 title="4. Create the sitemap" >
<p>
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 <strong>processing pipeline</strong>. Then, the <strong>sitemap</strong> can select the pipeline based on the details of the browser request.
</p>
<p>
To tell Cocoon how to process requests made to <code>html-pdf</code>,
copy the following snippet to a file named <strong>sitemap.xmap</strong> in the
<note>The important thing here is the first <strong>map:match</strong> 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.
</note>
<note>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.</note>
</s2>
<s2 title="5. Test the HTML publishing" >
<p>
At this point you should be able to display the results in HTML:
should display the second page with "Yes it works" in big red letters.
</li>
</ul>
</s2>
</s1>
<s1 title="Summary">
<p>
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.
</p>
<p>
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 transforms, one
for each target format.
</p>
<p>
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.
</p>
</s1>
<s1 title="Tips">
<s2 title="Tip 1: Dynamic XML data">
<p>
Using dynamic XML as the data source is very easy because the Cocoon FileGenerator can read URLs as well.
</p>
<p>
If you add the map:match element shown in bold below <strong>before</strong> the existing map:match elements in your sitemap.xmap file, requesting
