freemarker.template
Class Template

java.lang.Object
  |
  +--freemarker.template.Template

public class Template
extends java.lang.Object

An application or servlet can instantiate a subclass of Template to compile and process an HTML template.

You can pass the filename of the template to the constructor, in which case it is compiled immediately. Once compiled, the template is stored in an an efficient data structure for later use.

To process the template and produce HTML, call the process() method, which takes a tree of TemplateModel objects as its data model. The root node of the tree must be a TemplateModelRoot.

Any error messages from exceptions thrown by the data model, or generated by the Template during compilation or processing, will be thrown up to the caller to deal with.

Version:
$Id: Template.java,v 1.60 2002/04/26 23:02:42 revusky Exp $

Field Summary
static boolean CLASSIC_COMPATIBILITY
           
protected  TemplateElement rootElement
           
 
Constructor Summary
Template()
          Constructs an empty template.
Template(java.io.File file)
          Deprecated. Expect this to be removed later. You should either pass in a Reader, or an explicit encoding.
Template(java.io.InputStream stream)
          Deprecated. Expect this to be removed later. You should either pass in a Reader, or an explicit encoding.
Template(java.io.Reader stream)
          Constructs a template by compiling it from an Reader.
Template(java.lang.String filePath)
          Deprecated. Expect this to be removed later. You should either pass in a Reader, or an explicit encoding.
Template(TemplateCache cache, java.io.InputStream is)
           
Template(TemplateCache cache, java.io.InputStream is, java.util.Locale locale)
           
Template(TemplateCache cache, java.io.InputStream is, java.lang.String encoding)
           
Template(TemplateCache cache, java.io.Reader r, java.util.Locale locale)
           
 
Method Summary
 void addFunction(Function function)
          Adds a function to the template.
 void compileFromFile(java.io.File file)
          Deprecated. Expect this to be removed later. You should either pass in a Reader, or an explicit encoding.
 void compileFromFile(java.lang.String filePath)
          Deprecated. Expect this to be removed later. You should either pass in a Reader, or an explicit encoding.
 void compileFromStream(java.io.InputStream stream)
          Deprecated. Expect this to be removed later. You should either pass in a Reader, or an explicit encoding.
 void compileFromStream(java.io.InputStream stream, java.lang.String encoding)
          Compiles the template from an InputStream, using the specified character encoding.
 void compileFromStream(java.io.Reader stream)
          Compiles the template from a Reader.
 void dump(java.io.PrintStream ps)
          Dump the raw template in canonical form.
 void dump(java.io.PrintWriter pw)
          Dump the raw template in canonical form.
 TemplateCache getCache()
          Retrieve the cache that this object is stored in.
static boolean getDebugMode()
           
 java.lang.String getEncoding()
           
 Function getFunction(java.lang.String name)
          Retrieves a function from the template.
 java.util.Set getFunctionNames()
           
 java.util.Locale getLocale()
           
 java.lang.String getName()
           
 void process(TemplateModelRoot modelRoot, java.io.OutputStream out)
          Processes the template, using data from a template model, and outputs the resulting HTML to an output stream using the encoding for the template.
 void process(TemplateModelRoot modelRoot, java.io.Writer out)
          Processes the template, using data from a template model, and outputs the resulting HTML to a Writer.
 void process(TemplateModelRoot modelRoot, java.io.Writer out, java.lang.Object dummy)
          Processes the contents of this TemplateElement and outputs the resulting text to a Writer.
 void process(java.io.Writer out)
          Processes the template, using an empty data model, and outputs the resulting HTML to a Writer.
 void setCache(TemplateCache cache)
          Sets the cache that this object is stored in.
static void setClassicCompatibility(boolean b)
          Sets a flag to indicate that we should run in "classic compatibility mode".
static void setDebugMode(boolean b)
          If the debug mode is set to true (the default currently) all stack traces thrown by the process() method are simply output to the output stream (the web client in the case of a servlet-based app.) If it is false, the exception is simply rethrown and it is up to the application programmer to catch the exception and deal with it gracefully.
 void setEncoding(java.lang.String encoding)
           
 void setLocale(java.util.Locale locale)
           
 void setName(java.lang.String name)
           
 java.lang.String toString(TemplateModelRoot root)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

rootElement

protected TemplateElement rootElement

CLASSIC_COMPATIBILITY

public static boolean CLASSIC_COMPATIBILITY
Constructor Detail

Template

public Template()
Constructs an empty template.

Template

public Template(java.lang.String filePath)
         throws java.io.IOException
Deprecated. Expect this to be removed later. You should either pass in a Reader, or an explicit encoding.

Constructs a template by compiling it from a file. Calls compileFromFile().
Parameters:
filePath - the absolute path of the template file to be compiled.

Template

public Template(java.io.File file)
         throws java.io.IOException
Deprecated. Expect this to be removed later. You should either pass in a Reader, or an explicit encoding.

Constructs a template by compiling it from a file. Calls compileFromFile().
Parameters:
file - a File representing the template file to be compiled.

Template

public Template(java.io.InputStream stream)
         throws java.io.IOException
Deprecated. Expect this to be removed later. You should either pass in a Reader, or an explicit encoding.

Constructs a template by compiling it from an InputStream. Calls compileFromStream().
Parameters:
stream - an InputStream from which the template can be read.

Template

public Template(java.io.Reader stream)
         throws java.io.IOException
Constructs a template by compiling it from an Reader. Calls compileFromStream().
Parameters:
stream - a Reader from which the template can be read.

Template

public Template(TemplateCache cache,
                java.io.InputStream is)
         throws java.io.IOException

Template

public Template(TemplateCache cache,
                java.io.InputStream is,
                java.lang.String encoding)
         throws java.io.IOException

Template

public Template(TemplateCache cache,
                java.io.InputStream is,
                java.util.Locale locale)
         throws java.io.IOException

Template

public Template(TemplateCache cache,
                java.io.Reader r,
                java.util.Locale locale)
         throws java.io.IOException
Method Detail

setDebugMode

public static void setDebugMode(boolean b)
If the debug mode is set to true (the default currently) all stack traces thrown by the process() method are simply output to the output stream (the web client in the case of a servlet-based app.) If it is false, the exception is simply rethrown and it is up to the application programmer to catch the exception and deal with it gracefully.

getDebugMode

public static boolean getDebugMode()

setClassicCompatibility

public static void setClassicCompatibility(boolean b)
Sets a flag to indicate that we should run in "classic compatibility mode". In this mode, the == or != comparison between, say, 1 and "1" resolves to true. In the default mode, a comparison of a number with a string throws an exception since it is indicative of a logical flaw in the code. Also, in classic compatibility mode, a single scalar will be treated as a one-item list in an iteration.

getLocale

public java.util.Locale getLocale()

setCache

public void setCache(TemplateCache cache)
Sets the cache that this object is stored in.

getCache

public TemplateCache getCache()
Retrieve the cache that this object is stored in.

compileFromStream

public void compileFromStream(java.io.Reader stream)
                       throws java.io.IOException
Compiles the template from a Reader. If the template has already been compiled, this method does nothing.
Parameters:
stream - an Reader from which the template can be read.

compileFromFile

public void compileFromFile(java.io.File file)
                     throws java.io.IOException
Deprecated. Expect this to be removed later. You should either pass in a Reader, or an explicit encoding.

Reads an unparsed template from a file, by getting the file's FileInputStream and using it to call compileFromStream(), using the platform's default character encoding.
Parameters:
file - a File representing the template file to be compiled.

compileFromStream

public void compileFromStream(java.io.InputStream stream)
                       throws java.io.IOException
Deprecated. Expect this to be removed later. You should either pass in a Reader, or an explicit encoding.

Reads the unparsed template from an InputStream, using the platform's default character encoding. If the template has already been compiled, this method does nothing.
Parameters:
stream - an InputStream from which the template can be read.

compileFromStream

public void compileFromStream(java.io.InputStream stream,
                              java.lang.String encoding)
                       throws java.io.IOException
Compiles the template from an InputStream, using the specified character encoding. If the template has already been compiled, this method does nothing.
Parameters:
stream - an InputStream from which the template can be read.
encoding - the character encoding of the input stream

compileFromFile

public void compileFromFile(java.lang.String filePath)
                     throws java.io.IOException
Deprecated. Expect this to be removed later. You should either pass in a Reader, or an explicit encoding.

Reads an unparsed template from a file, by getting the file's FileInputStream and using it to call compileFromStream(), using the platform's default character encoding.
Parameters:
filePath - the absolute path of the template file to be compiled.

addFunction

public void addFunction(Function function)
Adds a function to the template.

getFunction

public Function getFunction(java.lang.String name)
Retrieves a function from the template. Called by FunctionCalls at run-time.

getFunctionNames

public java.util.Set getFunctionNames()
Returns:
a Set of function names (String objects) that have been defined for this template.

process

public void process(TemplateModelRoot modelRoot,
                    java.io.Writer out,
                    java.lang.Object dummy)
             throws TemplateException,
                    java.io.IOException
Processes the contents of this TemplateElement and outputs the resulting text to a Writer.
Parameters:
modelRoot - the root node of the data model.
out - a Writer to send the output to.
dummy - A dummy argument that is not used. It is there as a convenience to keep legacy code compilable.

process

public void process(TemplateModelRoot modelRoot,
                    java.io.Writer out)
             throws TemplateException,
                    java.io.IOException
Processes the template, using data from a template model, and outputs the resulting HTML to a Writer. If the DEBUG_MODE is set to true, the stacktrace of any exception thrown is simply output to the (web) client. Otherwise, the exception is simply rethrown for the caller to handle.
Parameters:
modelRoot - the root node of the data model. If null, an empty data model is used.
out - a Writer to output the HTML to.

toString

public java.lang.String toString(TemplateModelRoot root)
                          throws TemplateException,
                                 java.io.IOException
Returns:
the processed template as a string.

process

public void process(java.io.Writer out)
             throws TemplateException,
                    java.io.IOException
Processes the template, using an empty data model, and outputs the resulting HTML to a Writer.
Parameters:
out - a Writer to output the HTML to.

process

public void process(TemplateModelRoot modelRoot,
                    java.io.OutputStream out)
             throws TemplateException,
                    java.io.IOException
Processes the template, using data from a template model, and outputs the resulting HTML to an output stream using the encoding for the template.
Parameters:
modelRoot - the root node of the data model. If null, an empty data model is used.
out - an OutputStream to output the HTML to.

dump

public void dump(java.io.PrintWriter pw)
Dump the raw template in canonical form.

dump

public void dump(java.io.PrintStream ps)
Dump the raw template in canonical form.

getEncoding

public java.lang.String getEncoding()

setEncoding

public void setEncoding(java.lang.String encoding)

setLocale

public void setLocale(java.util.Locale locale)

setName

public void setName(java.lang.String name)

getName

public java.lang.String getName()