org.howardism.ant
Class WebTemplate

java.lang.Object
  org.apache.tools.ant.ProjectComponent
      org.apache.tools.ant.Task
          org.apache.tools.ant.taskdefs.MatchingTask
              org.howardism.ant.WebTemplate

All Implemented Interfaces:

org.apache.tools.ant.types.selectors.SelectorContainer

public class WebTemplate

extends org.apache.tools.ant.taskdefs.MatchingTask

This Ant task will create files by combining templates and data files using the StringTemplate formatting scheme.

While this is most often used to create web pages, it can create any sort of file. We could best describe this process by way of an example... Assume we have the following "source" files:

• htmldata/TopTemplate.st
• htmldata/footer.st
• htmldata/index.htm
• htmldata/services.htm

What we want is another directory that contains the finished HTML files, as in:

• html/index.html
• html/services.html

In this example, index.htm and services.htm are "data" files, and the content inside them is read and supplied to a "template" file. The template file shows where to insert the contents from the data file as well as any other processing (like including other files, i.e. the footer.st file).

Suppose that index.htm had the following contents:

<title>Simple Example</title>
 <body>
   <p>
     This is just a simple example of simple data-only content.
     It will be inserted into a prettier HTML page.
   </p>
 </body>

And lets also suppose that the TopTemplate.st file contains the following StringTemplate contents:

<html>
   <head>
     <title>My Site: $title$</title>
   </head>
   <body bgcolor="pink">
     $content$
     $footer()$
   </body>
 </html>

The goal in this is that the "template" file looks more like the finished HTML file, but is data-less. The "data" file is a more simple, easier- to-maintain HTML file, whose contents are inserted into the template at the $content$ location (and the "title" of the HTML file will be inserted at the $title$ location).

The other thing you will notice is the use of $footer()$. This will take the contents of the footer.st file and insert it directly the resulting HTML file.

You obviously have two questions ... let me provide some answers. First, the Ant task code to make this entire conversion process is as follows (this assumes that you have a legitimate Ant build.xml file):

<webtemplate src="htmldata" dest="html"
     template="TopTemplate" 
     includes="**/*.htm"  ext=".html" />

This task will take each file that ends in ".htm" in the source directory and use it as the contents applied to the "TopTemplate.st" template file. Each resulting converted file will be dropped in the "html" directory with an extension of "html".

Not too bad, eh? Now, let's answer your other question... why? First, it can be easier to create a web site with a single file that represents the "look and feel" or style and have each web page's contents live in a simpler file that has no formatting. In addition, you can easier break the template out into pieces and "include" them.

The other thing that you can do is have the task suck up attributes available to the template from a properties file. This is nice when used in combination with the <propertyfile> task, as in:

<propertyfile file="default.properties">
			<entry key="year" type="date" operation="=" value="now" pattern="yyyy"/>
			<entry key="today" type="date" operation="=" value="now" pattern="dd MMMM yyyy"/>
 </propertyfile>
 
 <webtemplate src="htmldata" dest="html"
     template="TopTemplate" propertyFile="default.properties"
     includes="**/*.htm"  ext=".html">
 </webtemplate>
 

 You can also set these name=values pairs as "text" within the
 opening and closing "webtemplate" tags.
 
 
 

 See my web site
 for a better description of this.
 















Constructor Summary
WebTemplate()



           
 



Method Summary




 void
addText(java.lang.String message)



          Called with CDATA-type text that was embedded in this task.



 org.apache.tools.ant.types.Mapper
createMapper()



          Defines the FileNameMapper to use (nested mapper element).



 void
execute()



          Execute the task



 void
setDest(java.io.File destDir)



          Set the destination directory to place converted files into.



 void
setEngine(java.lang.String engine)



          Set the "engine" parameter.



 void
setExt(java.lang.String ext)



          Set the extension which converted files should have.



 void
setPropertyFile(java.io.File propFile)



          Set the "propertyFile" attribute to the webTemplate task.



 void
setSrc(java.io.File srcDir)



          Set the source directory in which to find files to convert.



 void
setTemplate(java.lang.String template)



          Set the StringTemplate template file to use.


 
Methods inherited from class org.apache.tools.ant.taskdefs.MatchingTask
add, addAnd, addContains, addContainsRegexp, addCustom, addDate, addDepend, addDepth, addDifferent, addFilename, addMajority, addModified, addNone, addNot, addOr, addPresent, addSelector, addSize, addType, appendSelector, createExclude, createExcludesFile, createInclude, createIncludesFile, createPatternSet, getSelectors, hasSelectors, selectorCount, selectorElements, setCaseSensitive, setDefaultexcludes, setExcludes, setExcludesfile, setFollowSymlinks, setIncludes, setIncludesfile, setProject, XsetIgnore, XsetItems
 
Methods inherited from class org.apache.tools.ant.Task
getDescription, getLocation, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, init, log, log, maybeConfigure, perform, reconfigure, setDescription, setLocation, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType
 
Methods inherited from class org.apache.tools.ant.ProjectComponent
getProject
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 








Constructor Detail



WebTemplate
public WebTemplate()






Method Detail



setTemplate
public void setTemplate(java.lang.String template)

Set the StringTemplate template file to use.


Parameters:
template - String containing the name of the template
     file. Note: This does not end in .st, as
     that is assumed.





setSrc
public void setSrc(java.io.File srcDir)

Set the source directory in which to find files to convert.


Parameters:
srcDir - directory to find input file in.





setDest
public void setDest(java.io.File destDir)

Set the destination directory to place converted files into.


Parameters:
destDir - directory to place output file into.





setExt
public void setExt(java.lang.String ext)

Set the extension which converted files should have.
 If unset, files will not be renamed.


Parameters:
ext - File extension to use for converted files.





setEngine
public void setEngine(java.lang.String engine)

Set the "engine" parameter. This defaults to "stringtemplate" to
 use the org.antlr.stringtemplate engine.


Parameters:
engine - The engine to set.





addText
public void addText(java.lang.String message)
             throws org.apache.tools.ant.BuildException

Called with CDATA-type text that was embedded in this task.
 

 For instance, given an WebTemplate task that looks like:
 
 
<webtemplate src="htmldata" dest="html"
     includes="**/*.htm"  ext=".html">
   name=redEric
   code=level5
   type=admin
 </webtemplate>
 

 The attributes embedded between the task's opening and
 closing tags are parsed like any normal properties or
 resource file. These variables are then made available
 to the template engine.
 


Parameters:
message - The text of the data given to us
Throws:
org.apache.tools.ant.BuildException - If we couldn't parse the text





setPropertyFile
public void setPropertyFile(java.io.File propFile)
                     throws org.apache.tools.ant.BuildException

Set the "propertyFile" attribute to the webTemplate task. This
 should specify a real file that contain normal name=value pairs.
 This data is available to the template engine.


Parameters:
propFile - 
Throws:
org.apache.tools.ant.BuildException





createMapper
public org.apache.tools.ant.types.Mapper createMapper()
                                               throws org.apache.tools.ant.BuildException

Defines the FileNameMapper to use (nested mapper element).



Returns:
the mapper to use for file name translations.
Throws:
org.apache.tools.ant.BuildException - if more than one mapper is defined.





execute
public void execute()
             throws org.apache.tools.ant.BuildException

Execute the task



Throws:
org.apache.tools.ant.BuildException - is there is a problem in the task execution.