freemarker.template
Class Template

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

public class Template
extends java.lang.Object
implements TemplateProcessor

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 included as HTML comments in the output.

To facilitate multithreading, Template objects are immutable; if you need to recompile a template, you must make a new Template object. In most cases, it will be sufficient to let a TemplateCache do this for you.

See Also:
TemplateCache

Constructor Summary
Template()
          Constructs an empty template.
Template(java.io.File file)
          Constructs a template by compiling it from a file.
Template(java.io.InputStream stream)
          Constructs a template by compiling it from an InputStream.
Template(java.io.InputStreamReader stream)
          Constructs a template by compiling it from an InputStreamReader.
Template(java.lang.String filePath)
          Constructs a template by compiling it from a file.
 
Method Summary
 void addFunction(freemarker.template.instruction.FunctionInstruction function)
          Adds a function to the template.
 void compileFromFile(java.io.File file)
          Reads and compiles a template from a file, by getting the file's FileInputStream and using it to call compileFromStream(), using the platform's default character encoding.
 void compileFromFile(java.lang.String filePath)
          Reads and compiles a template from a file, by getting the file's FileInputStream and using it to call compileFromStream(), using the platform's default character encoding.
 void compileFromStream(java.io.InputStream stream)
          Compiles the template from an InputStream, using the platform's default character encoding.
 void compileFromStream(java.io.InputStreamReader stream)
          Compiles the template from an InputStreamReader.
protected  TemplateProcessor compileText(java.lang.String text)
          Compiles the template text using the standard parser and builder classes.
static java.lang.String formatErrorMessage(java.lang.String errorMessage)
          Used by FreeMarker classes to format an error message as an HTML comment.
 freemarker.template.instruction.FunctionInstruction getFunction(java.lang.String name)
          Retrieves a function from the template.
 java.util.Set getFunctionNames()
           
static java.lang.String getStackTrace(java.lang.Exception e)
          Used by FreeMarker classes to format a stack trace as a string.
 TemplateCache getTemplateCache()
          Gets the TemplateCache that this template belongs to.
 void process(java.io.PrintWriter out)
          Processes the template, using an empty data model, and outputs the resulting HTML to a PrintWriter.
 void process(TemplateModelRoot modelRoot, java.io.PrintWriter out)
          Processes the template, using data from a template model, and outputs the resulting HTML to a PrintWriter.
 void setTemplateCache(TemplateCache cache)
          Sets the TemplateCache that this template belongs to.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Template

public Template()
Constructs an empty template.

Template

public Template(java.lang.String filePath)
         throws java.io.IOException
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
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
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.InputStreamReader stream)
         throws java.io.IOException
Constructs a template by compiling it from an InputStreamReader. Calls compileFromStream().
Parameters:
stream - an InputStreamReader from which the template can be read.
Method Detail

compileFromFile

public void compileFromFile(java.lang.String filePath)
                     throws java.io.IOException
Reads and compiles a 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.

compileFromFile

public void compileFromFile(java.io.File file)
                     throws java.io.IOException
Reads and compiles a 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
Compiles the 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.InputStreamReader stream)
                       throws java.io.IOException
Compiles the template from an InputStreamReader. If the template has already been compiled, this method does nothing.
Parameters:
stream - an InputStreamReader from which the template can be read.

compileText

protected TemplateProcessor compileText(java.lang.String text)
Compiles the template text using the standard parser and builder classes. To provide different compilation behavior, subclasses need only override this method.
Parameters:
text - the text to compile.
Returns:
a TemplateProcessor representing the compiled template.

setTemplateCache

public void setTemplateCache(TemplateCache cache)
Sets the TemplateCache that this template belongs to. IncludeInstruction objects will be able to request this TemplateCache at run-time.
Parameters:
cache - the TemplateCache that this template belongs to.

getTemplateCache

public TemplateCache getTemplateCache()
Gets the TemplateCache that this template belongs to.
Returns:
the TemplateCache that this template belongs to.

addFunction

public void addFunction(freemarker.template.instruction.FunctionInstruction function)
Adds a function to the template. Called by the TemplateBuilder at compile-time.

getFunction

public freemarker.template.instruction.FunctionInstruction getFunction(java.lang.String name)
Retrieves a function from the template. Called by CallInstructions 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.PrintWriter out)
Processes the template, using data from a template model, and outputs the resulting HTML to a PrintWriter.
Specified by:
process in interface TemplateProcessor
Parameters:
modelRoot - the root node of the data model. If null, an empty data model is used.
out - a PrintWriter to output the HTML to.

process

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

formatErrorMessage

public static java.lang.String formatErrorMessage(java.lang.String errorMessage)
Used by FreeMarker classes to format an error message as an HTML comment.

getStackTrace

public static java.lang.String getStackTrace(java.lang.Exception e)
Used by FreeMarker classes to format a stack trace as a string.