Package freemarker.template

Class Template

java.lang.Object
freemarker.core.Configurable
freemarker.core.TemplateCore
freemarker.template.Template
public class Template extends TemplateCore

A core FreeMarker API that represents a compiled template. Typically, you will use a Configuration object to instantiate a template. 

      Configuration cfg = new Configuration();
      ...
      Template myTemplate = cfg.getTemplate("myTemplate.html");

However, you can also construct a template directly by passing in to the appropriate constructor a java.io.Reader instance that is set to read the raw template text. The compiled template is stored in an an efficient data structure for later use.

To render the template, i.e. to merge it with a data model, and thus produce "cooked" output, call the process method.

Any error messages from exceptions thrown during compilation will be included in the output stream and thrown back to the calling code. To change this behavior, you can install custom exception handlers using Configurable.setTemplateExceptionHandler(TemplateExceptionHandler) on a Configuration object (for all templates belonging to a configuration) or on a Template object (for a single template).

It's not legal to modify the values of FreeMarker settings: a) while the template is executing; b) if the template object is already accessible from multiple threads.

  • Field Details

  • Constructor Details

    • Template

      protected Template(String name, Configuration cfg, CodeSource codeSource)
      A prime constructor to which all other constructors should delegate directly or indirectly.

    • Template

      public Template(String name, Reader reader, Configuration cfg, String encoding, CodeSource codeSource) throws IOException
      Constructs a template from a character stream.
      Parameters:
      name - the path of the template file relative to the directory what you use to store the templates. See getName() for more details.
      reader - the character stream to read from. It will always be closed (Reader.close()).
      cfg - the Configuration object that this Template is associated with. If this is null, the "default" Configuration object is used, which is highly discouraged, because it can easily lead to erroneous, unpredictable behaviour. (See more here...)
      encoding - This is the encoding that we are supposed to be using. If this is non-null (It's not actually necessary because we are using a Reader) then it is checked against the encoding specified in the FTL header -- assuming that is specified, and if they don't match a WrongEncodingException is thrown.
      codeSource - the code source used to determine the security privileges for the template based on the Java policy in effect when it is run within a secured environment. Can be null, which is treated as being equivalent to untrusted code.
      Throws:
      IOException

    • Template

      public Template(String name, Reader reader, Configuration cfg, String encoding) throws IOException
      Throws:
      IOException

    • Template

      public Template(String name, Reader reader, Configuration cfg) throws IOException
      This is equivalent to Template(name, reader, cfg, null)
      Throws:
      IOException

    • Template

      public Template(String name, Reader reader) throws IOException
      Deprecated.
      This constructor uses the "default" Configuration instance, which can easily lead to erroneous, unpredictable behaviuour. See more here....
      Constructs a template from a character stream. This is the same as the 3 parameter version when you pass null as the cfg parameter.
      Throws:
      IOException

  • Method Details

    • getAbsoluteOffset

      public int getAbsoluteOffset(int line, int column)

    • readInTemplateText

      protected void readInTemplateText(Reader reader) throws IOException
      Throws:
      IOException

    • getPlainTextTemplate

      public static Template getPlainTextTemplate(String name, String content, Configuration config)
      Returns a trivial template, one that is just a single block of plain text, no dynamic content. (Used by the cache module to create unparsed templates.)
      Parameters:
      name - the path of the template file relative to the directory what you use to store the templates. See getName() for more details.
      content - the block of text that this template represents
      config - the configuration to which this template belongs

    • setStripWhitespace

      public void setStripWhitespace(boolean stripWhitespace)

    • process

      public void process(Object rootMap, Writer out) throws TemplateException, IOException
      Processes the template, using data from the map, and outputs the resulting text to the supplied Writer The elements of the map are converted to template models using the default object wrapper returned by the getObjectWrapper() method of the Configuration.
      Parameters:
      rootMap - the root node of the data model. If null, an empty data model is used. Can be any object that the effective object wrapper can turn into a TemplateHashModel. Basically, simple and beans wrapper can turn java.util.Map objects into hashes and the Jython wrapper can turn both a PyDictionary as well as any object that implements __getitem__ into a template hash. Naturally, you can pass any object directly implementing TemplateHashModel as well.
      out - a Writer to output the text to.
      Throws:
      TemplateException - if an exception occurs during template processing
      IOException - if an I/O exception occurs during writing to the writer.

    • process

      public void process(Object rootMap, Writer out, ObjectWrapper wrapper, TemplateNodeModel rootNode) throws TemplateException, IOException
      Processes the template, using data from the root map object, and outputs the resulting text to the supplied writer, using the supplied object wrapper to convert map elements to template models.
      Parameters:
      rootMap - the root node of the data model. If null, an empty data model is used. Can be any object that the effective object wrapper can turn into a TemplateHashModel Basically, simple and beans wrapper can turn java.util.Map objects into hashes and the Jython wrapper can turn both a PyDictionary as well as any object that implements __getitem__ into a template hash. Naturally, you can pass any object directly implementing TemplateHashModel as well.
      wrapper - The object wrapper to use to wrap objects into TemplateModel instances. If null, the default wrapper retrieved by Configurable.getObjectWrapper() is used.
      out - the writer to output the text to.
      rootNode - The root node for recursive processing, this may be null.
      Throws:
      TemplateException - if an exception occurs during template processing
      IOException - if an I/O exception occurs during writing to the writer.

    • process

      public void process(Object rootMap, Writer out, ObjectWrapper wrapper) throws TemplateException, IOException
      Processes the template, using data from the root map object, and outputs the resulting text to the supplied writer, using the supplied object wrapper to convert map elements to template models.
      Parameters:
      rootMap - the root node of the data model. If null, an empty data model is used. Can be any object that the effective object wrapper can turn into a TemplateHashModel Basically, simple and beans wrapper can turn java.util.Map objects into hashes and the Jython wrapper can turn both a PyDictionary as well as any object that implements __getitem__ into a template hash. Naturally, you can pass any object directly implementing TemplateHashModel as well.
      wrapper - The object wrapper to use to wrap objects into TemplateModel instances. If null, the default wrapper retrieved by Configurable.getObjectWrapper() is used.
      out - the writer to output the text to.
      Throws:
      TemplateException - if an exception occurs during template processing
      IOException - if an I/O exception occurs during writing to the writer.

    • createProcessingEnvironment

      public Environment createProcessingEnvironment(Object rootMap, Writer out, ObjectWrapper wrapper) throws TemplateException
      Creates a Environment object, using this template, the data model provided as the root map object, and the supplied object wrapper to convert map elements to template models. You can then call Environment.process() on the returned environment to set off the actual rendering. Use this method if you want to do some special initialization on the environment before template processing, or if you want to read the environment after template processing.

      Example:

      This: 

       Environment env = myTemplate.createProcessingEnvironment(root, out, null);
 env.process();
      is equivalent with this: 
       myTemplate.process(root, out);
      But with createProcessingEnvironment, you can manipulate the environment before and after the processing: 
       Environment env = myTemplate.createProcessingEnvironment(root, out);
 env.include("include/common.ftl", null, true);  // before processing
 env.process();
 TemplateModel x = env.getVariable("x");  // after processing
      Parameters:
      rootMap - the root node of the data model. If null, an empty data model is used. Can be any object that the effective object wrapper can turn into a TemplateHashModel Basically, simple and beans wrapper can turn java.util.Map objects into hashes and the Jython wrapper can turn both a PyDictionary as well as any object that implements __getitem__ into a template hash. Naturally, you can pass any object directly implementing TemplateHashModel as well.
      wrapper - The object wrapper to use to wrap objects into TemplateModel instances. If null, the default wrapper retrieved by Configurable.getObjectWrapper() is used.
      out - the writer to output the text to.
      Returns:
      the Environment object created for processing
      Throws:
      TemplateException - if an exception occurs while setting up the Environment object.

    • createProcessingEnvironment

      public Environment createProcessingEnvironment(Object rootMap, Writer out) throws TemplateException, IOException
      Same as createProcessingEnvironment(rootMap, out, null).
      Throws:
      IOException
      TemplateException
      See Also:

    • toString

      public String toString()
      Returns a string representing the raw template text in canonical form.
      Overrides:
      toString in class Object

    • getName

      public String getName()
      The path of the template file relative to the directory what you use to store the templates. For example, if the real path of template is "/www/templates/community/forum.fm", and you use ""/www/templates" as "directoryForTemplateLoading", then name should be "community/forum.fm". The name is used for example when you use <include ...> and you give a path that is relative to the current template, or in error messages when FreeMarker logs an error while it processes the template.

    • getConfiguration

      public Configuration getConfiguration()
      Returns the Configuration object associated with this template.

    • getParsingProblems

      public List<freemarker.core.parser.ParsingProblem> getParsingProblems()

    • hasParsingProblems

      public boolean hasParsingProblems()

    • addParsingProblem

      public void addParsingProblem(freemarker.core.parser.ParsingProblem problem)

    • setEncoding

      public void setEncoding(String encoding)
      Sets the character encoding to use for included files. Usually you don't set this value manually, instead it is assigned to the template upon loading.

    • getEncoding

      public String getEncoding()
      Returns the character encoding used for reading included files.

    • addImport

      public void addImport(freemarker.core.ast.LibraryLoad ll)
      Called by code internally to maintain a list of imports

    • setHeaderElement

      public void setHeaderElement(freemarker.core.ast.TemplateHeaderElement headerElement)

    • getHeaderElement

      public freemarker.core.ast.TemplateHeaderElement getHeaderElement()

    • declaresVariable

      public boolean declaresVariable(String name)

    • getDeclaredVariables

      public Set<String> getDeclaredVariables()

    • declareVariable

      public void declareVariable(String name)

    • setImplicitlyDeclaredVariables

      public void setImplicitlyDeclaredVariables(Set<String> names)
      Used internally, this is a complication necessary for backward compatibility in includes.

    • isImplicitlyDeclared

      public boolean isImplicitlyDeclared(String varname)
      only used internally, it says whether the variable was implicitly declared, that means not in a #var statement but either via a legacy #assign or as the name of a macro or as the namespace name in an #import This is rather tricky and only necessary for backward compatibility with older style #include's

    • strictVariableDeclaration

      public boolean strictVariableDeclaration()

    • setStrictVariableDeclaration

      public void setStrictVariableDeclaration(boolean strictVariableDeclaration)

    • getSource

      public String getSource(int beginColumn, int beginLine, int endColumn, int endLine)

    • getLine

      public String getLine(int lineNumber)

    • getTabAdjustedColumn

      public int getTabAdjustedColumn(int lineNumber, int column, int tabSize)

    • writeTextAt

      public void writeTextAt(Writer out, int beginColumn, int beginLine, int endColumn, int endLine) throws IOException
      Throws:
      IOException

    • writeTemplateText

      public void writeTemplateText(Writer out) throws IOException
      Throws:
      IOException

    • setLineSaysLeftTrim

      public void setLineSaysLeftTrim(int i)

    • setLineSaysRightTrim

      public void setLineSaysRightTrim(int i)

    • setLineSaysTrim

      public void setLineSaysTrim(int i)

    • setLineSaysNoTrim

      public void setLineSaysNoTrim(int i)

    • lineSaysLeftTrim

      public boolean lineSaysLeftTrim(int i)

    • lineSaysRightTrim

      public boolean lineSaysRightTrim(int i)

    • lineSaysNoTrim

      public boolean lineSaysNoTrim(int i)

    • markAsOutputtingLine

      public void markAsOutputtingLine(int lineNumber, boolean inMacro)

    • isOutputtingLine

      public boolean isOutputtingLine(int i, boolean inMacro)

    • getRootTreeNode

      public freemarker.core.ast.TemplateElement getRootTreeNode()
      Returns:
      the root TemplateElement object.
      Throws:
      SecurityException - if the getConfiguration().isSecure() returns true, there is a security manager in the JVM, and the caller of this method does not posess the "modifyTemplate" FreeMarker permission (since the retrieved root tree node is mutable).

    • setParent

      public void setParent(Configurable parent)
      Description copied from class: Configurable
      Reparenting support. This is used by Environment when it includes a template - the included template becomes the parent configurable during its evaluation.
      Overrides:
      setParent in class Configurable
      Throws:
      SecurityException - if the getConfiguration().isSecureTemplates() returns true, there is a security manager in the JVM, and the caller of this method does not posess the "modifyTemplate" FreeMarker permission.

    • getImports

      public List<freemarker.core.ast.LibraryLoad> getImports()

    • getCodeSource

      public CodeSource getCodeSource()

    • addPrefixNSMapping

      public void addPrefixNSMapping(String prefix, String nsURI)
      This is used internally.

    • getDefaultNS

      public String getDefaultNS()

    • getNamespaceForPrefix

      public String getNamespaceForPrefix(String prefix)
      Returns:
      the NamespaceUri mapped to this prefix in this template. (Or null if there is none.)

    • getPrefixForNamespace

      public String getPrefixForNamespace(String nsURI)
      Returns:
      the prefix mapped to this nsURI in this template. (Or null if there is none.)

    • getPrefixedName

      public String getPrefixedName(String localName, String nsURI)
      Returns:
      the prefixed name, based on the ns_prefixes defined in this template's header for the local name and node namespace passed in as parameters.

    • containingElements

      public List<freemarker.core.ast.TemplateElement> containingElements(int column, int line)
      Parameters:
      column - the column
      line - the line
      Returns:
      an array of the elements containing the given column and line numbers.
      Throws:
      SecurityException - if the getConfiguration().isSecureTemplates() returns true, there is a security manager in the JVM, and the caller of this method does not posess the "modifyTemplate" FreeMarker permission.