| <?xml version="1.0"?> |
| |
| <document> |
| |
| <properties> |
| <title>Texen</title> |
| <author email="jvanzyl@zenplex.com">Velocity Documentation Team</author> |
| </properties> |
| |
| <body> |
| |
| <section name="What is Texen?"> |
| |
| <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> |
| |
| </section> |
| |
| <section name="The TexenTask"> |
| |
| <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> |
| |
| <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> |
| <em>Control Template</em> |
| </p> |
| |
| <source><![CDATA[ |
| #* |
| |
| file: Control.vm |
| |
| This is the control template for our HTML |
| page generator! |
| |
| *# |
| |
| #set ($Planets = ["Earth", "Mars", "Venus"]) |
| |
| #foreach ($planet in $Planets) |
| |
| #set ($outputFile = $strings.concat([$planet, ".html"])) |
| $generator.parse("HtmlTemplate.vm", $outputFile, "planet", $planet) |
| |
| #end |
| ]]></source> |
| |
| <p> |
| <em>Worker Template</em> |
| </p> |
| |
| <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> |
| 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 border="0"> |
| <tr> |
| <th>Name</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td>templatePath</td> |
| <td><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></td> |
| </tr> |
| <tr> |
| <td>useClasspath</td> |
| <td><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></td> |
| </tr> |
| <tr> |
| <td>useResourceLoaderCache</td> |
| <td>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.</td> |
| </tr> |
| <tr> |
| <td>resourceLoaderModificationCheckInterval</td> |
| <td>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.</td> |
| </tr> |
| <tr> |
| <td>controlTemplate</td> |
| <td><b>[REQUIRED]</b> |
| Set the control template for the |
| generating process.</td> |
| </tr> |
| <tr> |
| <td>outputDirectory</td> |
| <td><b>[REQUIRED]</b> |
| Set the output directory. It will be |
| created if it doesn't exist.</td> |
| </tr> |
| <tr> |
| <td>outputFile</td> |
| <td><b>[REQUIRED]</b> |
| Set the output file for the |
| generation process.</td> |
| </tr> |
| <tr> |
| <td>outputEncoding</td> |
| <td>Set the output encoding.</td> |
| </tr> |
| <tr> |
| <td>inputEncoding</td> |
| <td>Set the input (template) encoding.</td> |
| </tr> |
| <tr> |
| <td>contextProperties</td> |
| <td>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></td> |
| </tr> |
| </table> |
| |
| </section> |
| |
| <section name="Predefined Context Objects"> |
| <p> |
| The Texen Ant task places several objects into the Context for you. |
| </p> |
| <table border="0"> |
| <tr> |
| <th>Name</th> |
| <th>Value</th> |
| </tr> |
| <tr> |
| <td>$generator</td> |
| <td> |
| This contains the the <a |
| href ="api/org/apache/velocity/texen/Generator.html">Generator</a> |
| instance used to output the text files. |
| </td> |
| </tr> |
| <tr> |
| <td>$outputDirectory</td> |
| <td> |
| This contains the the value of the outputDirectory property given to the Texen Ant Task. |
| </td> |
| </tr> |
| <tr> |
| <td>$strings</td> |
| <td> |
| 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. |
| </td> |
| </tr> |
| <tr> |
| <td>$files</td> |
| <td> |
| This contains the an instance of a <a |
| href="api/org/apache/velocity/texen/util/FileUtil.html">FileUtil</a> |
| object. |
| </td> |
| </tr> |
| <tr> |
| <td>$properties</td> |
| <td> |
| This contains the an instance of a <a |
| href="api/org/apache/velocity/texen/util/PropertiesUtil.html">PropertiesUtil</a> |
| object. |
| </td> |
| </tr> |
| </table> |
| |
| </section> |
| |
| </body> |
| </document> |
