blob: 06e2cb32b348c9509efe15b10b5b5897fa843526 [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--
Copyright 1999-2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!-- Content Stylesheet for Site -->
<!-- start the processing -->
<!-- ====================================================================== -->
<!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! -->
<!-- Main Page Section -->
<!-- ====================================================================== -->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
<meta name="author" value="Velocity Documentation Team">
<meta name="email" value="jvanzyl@zenplex.com">
<title>Velocity - Texen</title>
</head>
<body bgcolor="#ffffff" text="#000000" link="#525D76">
<table border="0" width="100%" cellspacing="0">
<!-- TOP IMAGE -->
<tr>
<td align="left">
<a href="http://jakarta.apache.org"><img src="http://jakarta.apache.org/images/jakarta-logo.gif" border="0"/></a>
</td>
<td align="right">
<a href="http://jakarta.apache.org/velocity/"><img src="./images/logo.gif" alt="Velocity" border="0"/></a>
</td>
</tr>
</table>
<table border="0" width="100%" cellspacing="4">
<tr><td colspan="2">
<hr noshade="" size="1"/>
</td></tr>
<tr>
<!-- LEFT SIDE NAVIGATION -->
<td width="20%" valign="top" nowrap="true">
<!-- ============================================================ -->
<p><strong>About</strong></p>
<ul>
<li> <a href="./index.html">Overview</a>
</li>
<li> <a href="./getting-started.html">Getting Started</a>
</li>
<li> <a href="http://jakarta.apache.org/builds/jakarta-velocity/">Download</a>
</li>
<li> <a href="./install.html">Install</a>
</li>
<li> <a href="./design.html">Design</a>
</li>
<li> <a href="./contributors.html">Contributors</a>
</li>
<li> <a href="./changes.html">ChangeLog</a>
</li>
<li> <a href="./code-standards.html">Coding Standards</a>
</li>
<li> <a href="./license.html">License</a>
</li>
<li> <a href="./todo.html">TODO</a>
</li>
<li> <a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Velocity">Report Issues</a>
</li>
</ul>
<p><strong>Community</strong></p>
<ul>
<li> <a href="./powered.html">Powered By Velocity</a>
</li>
<li> <a href="http://jakarta.apache.org/site/getinvolved.html">Get Involved</a>
</li>
<li> <a href="http://jakarta.apache.org/site/mail.html">Mailing Lists</a>
</li>
<li> <a href="http://www.apache.org/dev/version-control.html">Subversion Repositories</a>
</li>
</ul>
<p><strong>Docs</strong></p>
<ul>
<li> <a href="./user-guide.html">User's Guide (English)</a>
</li>
<li> <a href="./user-guide_fi.html">User's Guide (Finnish)</a>
</li>
<li> <a href="./user-guide_fr.html">User's Guide (French)</a>
</li>
<li> <a href="./user-guide_es.html">User's Guide (Spanish)</a>
</li>
<li> <a href="./developer-guide.html">Developer's Guide</a>
</li>
<li> <a href="./vtl-reference-guide.html">VTL Reference Guide</a>
</li>
<li> <a href="./specification.html">Specification</a>
</li>
<li> <a href="./api/index.html">Javadoc</a>
</li>
<li> <a href="http://wiki.apache.org/jakarta-velocity/">Wiki</a>
</li>
<li> <a href="http://wiki.apache.org/jakarta-velocity/VelocityFAQ">FAQ</a>
</li>
</ul>
<p><strong>Tools</strong></p>
<ul>
<li> <a href="./tools/index.html">Velocity Tools</a>
</li>
<li> <a href="./anakia.html">Anakia : XML->doc tool</a>
</li>
<li> <a href="./texen.html">Texen : text generation</a>
</li>
<li> <a href="./dvsl/index.html">DVSL : XML xformation</a>
</li>
<li> <a href="./veltag.html">Veltag : JSP taglib</a>
</li>
<li> <a href="./migration.html">Migration to Velocity</a>
</li>
<li> <a href="./devtools.html">Editors and IDEs</a>
</li>
</ul>
<p><strong>Comparisons</strong></p>
<ul>
<li> <a href="./ymtd/ymtd.html">YMTD</a>
</li>
<li> <a href="./differences.html">VM/WM Differences</a>
</li>
<li> <a href="./casestudy1.html">JSP vs. Velocity</a>
</li>
<li> <a href="./casestudy2.html">XMLC vs. Velocity</a>
</li>
</ul>
<p><strong>Site Translations</strong></p>
<ul>
<li> <a href="http://jakarta.apache.org/velocity/">English</a>
</li>
<li> <a href="http://www.jajakarta.org/velocity/">Japanese</a>
</li>
</ul>
</td>
<td width="80%" align="left" valign="top">
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="What is Texen?"><strong>What is Texen?</strong></a>
</font>
</td></tr>
<tr><td>
<p>
<blockquote>
<p>
Texen is a general purpose text generating utility. It is capable of
producing almost any sort of text output. Driven by Ant, essentially
an <a href="http://jakarta.apache.org/ant/">Ant</a> Task, Texen uses
a control template, an optional set of worker templates, and control
context to govern the generated output. Although TexenTask can be
used directly, it is usually subclassed to initialize your control
context before generating any output.
</p>
<p>
Texen was created to deal with the source generating requirements of
the Turbine web application framework. The <a href="http://jakarta.apache.org/turbine/torque.html">Torque</a> utility
in <a href="http://jakarta.apache.org/turbine/">Turbine</a>, 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 almost any
sort of text output!
</p>
</blockquote>
</p>
</td></tr>
<tr><td><br/></td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="The TexenTask"><strong>The TexenTask</strong></a>
</font>
</td></tr>
<tr><td>
<p>
<blockquote>
<p>
This trivial example, which shows how to use Texen from an Ant
build.xml, is intended to illustrate how the Texen mechanism works.
</p>
<p>
<em>Ant Build File</em>
</p>
<div align="left">
<table cellspacing="4" cellpadding="0" border="0">
<tr>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#ffffff"><pre>
&lt;project name=&quot;HtmlGenerator&quot; default=&quot;main&quot; basedir=&quot;.&quot;&gt;
&lt;taskdef name=&quot;texen&quot; classname=&quot;org.apache.velocity.texen.ant.TexenTask&quot;/&gt;
&lt;!-- ================================================================ --&gt;
&lt;!-- G E N E R A T E H T M L P A G E S --&gt;
&lt;!-- ================================================================ --&gt;
&lt;!-- This target will generate a set of HTML pages based on --&gt;
&lt;!-- the information in our control context. --&gt;
&lt;!-- ================================================================ --&gt;
&lt;target name=&quot;main&quot;&gt;
&lt;echo message=&quot;+------------------------------------------+&quot;/&gt;
&lt;echo message=&quot;| |&quot;/&gt;
&lt;echo message=&quot;| Generating HTML pages! |&quot;/&gt;
&lt;echo message=&quot;| |&quot;/&gt;
&lt;echo message=&quot;+------------------------------------------+&quot;/&gt;
&lt;texen
controlTemplate=&quot;Control.vm&quot;
outputDirectory=&quot;.&quot;
templatePath=&quot;.&quot;
outputFile=&quot;generation.report&quot;
/&gt;
&lt;/target&gt;
&lt;/project&gt;
</pre></td>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
</table>
</div>
<p>
<em>Control Template</em>
</p>
<div align="left">
<table cellspacing="4" cellpadding="0" border="0">
<tr>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#ffffff"><pre>
#*
file: Control.vm
This is the control template for our HTML
page generator!
*#
#set ($Planets = [&quot;Earth&quot;, &quot;Mars&quot;, &quot;Venus&quot;])
#foreach ($planet in $Planets)
#set ($outputFile = $strings.concat([$planet, &quot;.html&quot;]))
$generator.parse(&quot;HtmlTemplate.vm&quot;, $outputFile, &quot;planet&quot;, $planet)
#end
</pre></td>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
</table>
</div>
<p>
<em>Worker Template</em>
</p>
<div align="left">
<table cellspacing="4" cellpadding="0" border="0">
<tr>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#ffffff"><pre>
#*
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 = &quot;#ffffff&quot;)
&lt;html&gt;
&lt;head&gt;
&lt;title&gt;
Everything you wanted to know about $planet!
&lt;/title&gt;
&lt;/head&gt;
&lt;body bgcolor=&quot;$bgcolor&quot;&gt;
$planet is a great place to live!
&lt;/body&gt;
&lt;/html&gt;
</pre></td>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
</table>
</div>
<p>
Texen produces three html pages: Earth.html, Mars.html, and
Venus.html. To do something more 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>
See the Torque utility in Turbine for a full working example of
Texen. A standalone version of Torque is available <a href="http://jakarta.apache.org/builds/jakarta-turbine/release/">here</a>.
</p>
<table>
<tr>
<th bgcolor="#039acc" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Name
</font>
</th>
<th bgcolor="#039acc" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Description
</font>
</th>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
templatePath
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
<b>[REQUIRED]</b>
Set the path where Velocity will look
for templates using the file template
loader.
<b>This is only required if useClasspath is not turned on.</b>
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
useClasspath
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
<b>[REQUIRED]</b>
Set the use of the classpath in locating templates.
true means the classpath will be used.
<b>This is only required if templatePath is not set.</b>
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
useResourceLoaderCache
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Optional argument used when useClasspath is turned on.
See the <a href="developer-guide.html#Configuring Resource Loaders">Developer's Guide</a>
for details on resource caching.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
resourceLoaderModificationCheckInterval
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Optional argument used when useClasspath is turned on.
See the <a href="developer-guide.html#Configuring Resource Loaders">Developer's Guide</a>
for details on resource caching.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
controlTemplate
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
<b>[REQUIRED]</b>
Set the control template for the
generating process.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
outputDirectory
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
<b>[REQUIRED]</b>
Set the output directory. It will be
created if it doesn't exist.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
outputFile
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
<b>[REQUIRED]</b>
Set the output file for the
generation process.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
outputEncoding
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Set the output encoding.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
inputEncoding
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Set the input (template) encoding.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
contextProperties
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Set the context properties that will be
fed into the initial context be the
generating process starts.
<p>
We are going to do something special
for properties that have a "file.contents"
suffix: for these properties will pull
in the contents of the file and make
them available in the context. So for
a line like the following in a properties file:
<pre>license.file.contents = license.txt</pre>
We will pull in the contents of license.txt
and make it available in the context as
$license. This should make texen a little
more flexible.
</p>
</font>
</td>
</tr>
</table>
</blockquote>
</p>
</td></tr>
<tr><td><br/></td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Predefined Context Objects"><strong>Predefined Context Objects</strong></a>
</font>
</td></tr>
<tr><td>
<p>
<blockquote>
<p>
The Texen Ant task places several objects into the Context for you.
</p>
<table>
<tr>
<th bgcolor="#039acc" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Name
</font>
</th>
<th bgcolor="#039acc" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Value
</font>
</th>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
$generator
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
This contains the the <a href="api/org/apache/velocity/texen/Generator.html">Generator</a>
instance used to output the text files.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
$outputDirectory
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
This contains the the value of the outputDirectory property given to the Texen Ant Task.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
$strings
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
This contains the an instance of a <a href="http://jakarta.apache.org/commons/lang/apidocs/org/apache/commons/lang/StringUtils.html">StringUtils</a>
object.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
$files
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
This contains the an instance of a <a href="api/org/apache/velocity/texen/util/FileUtil.html">FileUtil</a>
object.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
$properties
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
This contains the an instance of a <a href="api/org/apache/velocity/texen/util/PropertiesUtil.html">PropertiesUtil</a>
object.
</font>
</td>
</tr>
</table>
</blockquote>
</p>
</td></tr>
<tr><td><br/></td></tr>
</table>
</td>
</tr>
<!-- FOOTER -->
<tr><td colspan="2">
<hr noshade="" size="1"/>
</td></tr>
<tr><td colspan="2">
<div align="center"><font color="#525D76" size="-1"><em>
Copyright &#169; 1999-2005, The Apache Software Foundation
</em></font></div>
</td></tr>
</table>
</body>
</html>
<!-- end the processing -->