All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class org.webmacro.engine.Template

java.lang.Object
   |
   +----org.webmacro.engine.Template

public abstract class Template
extends Object
Template objects represent the user defined layout into which the webmacro package will substitute values. It is a very simple kind of interpreted language containing text, blocks, and directives. Text is to be passed through verbatim. LList group text and directives into linear lists and sublists. Directives determine how subsequent blocks are to be processed and constitute the commands of the language.

The Template is lazily evaluated: it does not parse or open the supplied filename until it is used. Once it has parsed the file, it never alters its data. The intent is to allow a Template to be parsed once (somewhat expensive) and then used many times; and also not to incur any parsing costs at all if the Template is never actually used.


Constructor Index

 o Template()

Method Index

 o evaluate(Object)
Parse the Template against the supplied context data and return it as a string.
 o getParam(String)
A template may contain parameters, set by the #param directive.
 o getReader()
Get the stream the template should be read from.
 o parse()
Force the template to parse now.
 o toString()
Return a name for this template.
 o write(Writer, Object)
A macro has a write method which takes a context and applies it to the macro to create a resulting String value, which is then written to the supplied stream.

Constructors

 o Template
 public Template()

Methods

 o getReader
 protected abstract Reader getReader() throws IOException
Get the stream the template should be read from. Parse will call this method in order to locate a stream.

Throws: IOException
if unable to read template
 o toString
 public abstract String toString()
Return a name for this template. For example, if the template reads from a file you might want to mention which it is--will be used to produce error messages describing which template had a problem.

Overrides:
toString in class Object
 o parse
 public final void parse() throws IOException, ParseException
Force the template to parse now. Normally the template will not parse the supplied file until the data is actually needed. However if you want to parse all of your templates at the start of the application to avoid incurring this call during an interactive session, you can call the parse() function at an appropriate time. Alternately, you could call this function to reparse a template if you know that it has changed.

Throws: ParseException
if the sytax was invalid and we could not recover
Throws: IOException
if we could not successfullly read the parseTool
 o evaluate
 public final Object evaluate(Object data)
Parse the Template against the supplied context data and return it as a string. If the operation fails for some reason, such as unable to read template or unable to introspect the context then this method will return a null string.

 o write
 public final boolean write(Writer out,
                            Object data) throws IOException
A macro has a write method which takes a context and applies it to the macro to create a resulting String value, which is then written to the supplied stream. Something will always be written to the stream, even if the operation is not really successful because of a parse error (an error message will be written to the stream in that case.)

Returns:
whether the operation was a success
Throws: IOException
if there is a problem writing to the Writer
 o getParam
 public Object getParam(String name) throws IOException, ParseException
A template may contain parameters, set by the #param directive. These are statically evaluated during the parse phase of the template and shared between all users of the template. They are present so that the template can provide some meta information to its user as to what kind of data it expects to find in the Context, or other information about its use.

If the template has not already been parsed, it will be parsed. Thus this method may throw ParseException or IOException if there is some failure in accessing or parsing the template.

Throws: IOException
if an error occurred reading the template
Throws: ParseException
if an error occurred parsing the template

All Packages  Class Hierarchy  This Package  Previous  Next  Index