jfor/Cocoon 2 HOWTO: dynamic generation of RTF documents from XML with Cocoon 2.0x and jfor
This applies to the 2.0.x versions of Cocoon. In the meantime, the jfor license has been changed to an Apache-compatible one,
which allows jfor to be distributed with Cocoon 2.1.x, so that for 2.1.x you only need to enable the jfor block to activate
the generation of RTF documents by Cocoon.
A short technical note about how to activate RTF generation with Cocoon 2.
Written by Bertrand Delacrétaz, bdelacretaz@codeconsult.ch - February 13th, 2002.
Intro
- See http://www.jfor.org for more info about the jfor library that is used here to generate RTF.
- Keep in mind that jfor is still fairly limited in its layout abilities.
- This procedure has been tested with Cocoon 2.0.1.
- More info on Cocoon can be found at http://xml.apache.org/cocoon
How to activate and test dynamic RTF generation with Cocoon
Basically, as jfor cannot currently be distributed with Cocoon due to slight license incompatibilites, you must recompile Cocoon with
the jfor library (jfor.jar) to activate the RTF serializer in Cocoon.
- Download and unpack the Cocoon source code.
For V2.0.1 the file to download is called cocoon-2.0.1-src.something (where something is a format like "tar.gz") and
can be found under http://xml.apache.org/cocoon/dist/
- Make sure you can compile the standard Cocoon distribution
You will need a java compiler for this (tested with JDK 1.3.1, see Cocoon web site for more details about compiler requirements).
Follow the instructions found in the INSTALL file of the Cocoon distribution to compile it.
During compilation, you should see messages saying that "Classes of the optional package JFOR are not available".
This is correct as the standard Cocoon distribution does not include the required jfor JAR file.
- Add jfor.jar to the Cocoon source tree
Download the latest version of the jfor jar file from the "files" are of jfor's SourceForge site at http://sourceforge.net/projects/jfor
Copy jfor-XXX.jar (where XXX is jfor's version number) to the lib/optional subdirectory of your Cocoon source tree (the directory that contains
fop-XXX.jar, for example).
Recompile Cocoon as you did before, this time the "Classes of the optional package JFOR are not available" message should not appear.
- Install Cocoon
Follow Cocoon's INSTALL file instructions.
If you already have a tomcat installation (the web server that is often used to run Cocoon), it's just a matter of copying the cocoon.war
file generated during Cocoon compilation to the webapps directory of tomcat and restarting tomcat.
- Test Cocoon
For a standard tomcat/cocoon installation, http://localhost:8080/cocoon should show the Cocoon demonstration page ("Multimedia Hello World", etc.)
- Add the hello.rtf definition to the sitemap.xmap
This will activate an RTF version of the Cocoon "hello" demonstration page.
In the main sitemap.xmap file or your Cocoon installation (under the tomcat installation directory, in webapps/cocoon):
after this element that already exists:
<map:match pattern="hello.pdf">
. . .
</map:match>
add this one:
<map:match pattern="hello.rtf">
<map:generate src="docs/samples/hello-page.xml"/>
<map:transform src="stylesheets/page/simple-page2fo.xsl"/>
<map:serialize type="fo2rtf"/>
</map:match>
- Test the RTF serializer
If all goes well, requesting http://localhost:8080/cocoon/hello.rtf should deliver an RTF document saying "Hello, this is my first Cocoon page".
If it does, you're in business!
If not, your best bet is to look at the Cocoon log files under the WEB-INF/logs directory found under webapps/cocoon under the tomcat installation directory
- Where to go next
Study the above sitemap entry and the stylesheets/page/simple-page2fo.xsl to see how Cocoon is now able to generate RTF out of the hello-page.xml document.
The full range of Cocoon features (access to XML documents over HTTP, XML databases, dynamic generation, etc.) is now available for you to generate RTF documents!
Coda
Enjoy - and please let us know at feedback@jfor.org!
And, if you have a problem with jfor: help us solve it, contributions (code, documentation, etc.) are most welcome!