jvanzyl 00/11/08 09:30:06
Added: xdocs texen.xml
Log:
- adding docs for texen.
Revision Changes Path
1.1 jakarta-velocity/xdocs/texen.xml
Index: texen.xml
===================================================================
<?xml version="1.0"?>
<document>
<header>
<title>Texen</title>
<subtitle>Migration To Velocity</subtitle>
<authors>
<person name="Jason van Zyl" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="What is Texen?">
<p>
Texen is a general purpose text generating utility. You can
use it to easily produce any sort of text output. Texen uses a
control template, an optional set of worker templates, and control context
to govern the generated output. Texen is driven by Ant, and in
essense Texen is an <link href="http://jakarta.apache.org/ant/">Ant</link>
Task. You can use the TexenTask directly
if you wish, but it general you will probably subclass the
TexenTask in order to initialize your control context before
generating any output.
</p>
<p>
Texen was originally created to deal with the source generating
requirements of Turbine web application framework. The
<link href="http://java.apache.org/turbine/torque.html">Torque</link>
utility in <link href="http://java.apache.org/turbine/">Turbine</link>,
which is a subclass of the TexenTask, is responsible
for generating the SQL, and the Object-Relational mapping sources
for a Turbine project. This is only one example, you can use
Texen to generate any sort of text output!
</p>
</s1>
<s1 title="The TexenTask">
<p>
As mentioned previously, Texen is essentially an Ant Task. This
is a trivial example of how you would use Texen from an Ant build.xml.
This example is not very useful, but shows how the Texen mechanism
works.
</p>
<p>
<em>Ant Build File</em>
<source><![CDATA[
<project name="HtmlGenerator" default="main" basedir=".">
<taskdef name="texen" classname="org.apache.velocity.texen.ant.TexenTask"/>
<!-- ================================================================ -->
<!-- G E N E R A T E H T M L P A G E S -->
<!-- ================================================================ -->
<!-- This target will generate a set of HTML pages based on -->
<!-- the information in our control context. -->
<!-- ================================================================ -->
<target name="main">
<echo message="+------------------------------------------+"/>
<echo message="| |"/>
<echo message="| Generating HTML pages! |"/>
<echo message="| |"/>
<echo message="+------------------------------------------+"/>
<texen
controlTemplate="Control.vm"
outputDirectory="."
templatePath="."
outputFile="generation.report"
/>
</target>
</project>
]]></source>
</p>
<p>
<em>Control Template</em>
<source><![CDATA[
#*
file: Control.vm
This is the control template for our HTML
page generator!
*#
#set $Planets = ["Earth", "Mars", "Venus"]
#foreach ($planet in $Planets)
$outputFile = strings.concat([$planet, ".html"])
$generator.parse("HtmlTemplate.vm", $outputFile, "planet", $planet)
#end
]]></source>
</p>
<p>
<em>Worker Template</em>
<source><![CDATA[
#*
file: HtmlTemplate.vm
This is worker template, it is called by the
control template to produce useful output, or
not so useful in this case :-)
*#
#set $bgcolor = "#ffffff"
<html>
<head>
<title>
Everything you wanted to know about $planet!
</title>
</head>
<body bgcolor="$bgcolor">
$planet is a great place to live!
</body>
</html>
]]></source>
</p>
<p>
What will be produced are three html pages: Earth.html,
Mars.html, and Venus.html. This is a contrived example but
hopefully illustrates how the mechanism works. To do something
useful you would subclass the TexenTask, place some objects
in the control context and use the information placed in the
control context to generate useful output.
</p>
<p>
For a full working example of Texen, take a look at the Torque
utility in Turbine. There is a stand-alone version of Torque
available <link href="http://java.apache.org/turbine/tdk/">here</link>.
</p>
</s1>
</body>
</document>
