Home » freemarker-2.3.13 » freemarker.template » [javadoc | source]
freemarker.template
public class: Template [javadoc | source]
java.lang.Object
   freemarker.core.Configurable
      freemarker.template.Template

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.

Nested Class Summary:
public static class  Template.WrongEncodingException   
Field Summary
public static final  String DEFAULT_NAMESPACE_PREFIX     
public static final  String NO_NS_PREFIX     
Fields inherited from freemarker.core.Configurable:
LOCALE_KEY,  NUMBER_FORMAT_KEY,  TIME_FORMAT_KEY,  DATE_FORMAT_KEY,  DATETIME_FORMAT_KEY,  TIME_ZONE_KEY,  CLASSIC_COMPATIBLE_KEY,  TEMPLATE_EXCEPTION_HANDLER_KEY,  ARITHMETIC_ENGINE_KEY,  OBJECT_WRAPPER_KEY,  BOOLEAN_FORMAT_KEY,  OUTPUT_ENCODING_KEY,  URL_ESCAPING_CHARSET_KEY,  STRICT_BEAN_MODELS
Constructor:
 public Template(String name,
    Reader reader) throws IOException 
    Constructs a template from a character stream. This is the same as the 3 parameter version when you pass null as the cfg parameter.
     public Template(String name,
        Reader reader,
        Configuration cfg) throws IOException 
      This is equivalent to Template(name, reader, cfg, null)
     Template(String name,
        TemplateElement root,
        Configuration config) 
      This constructor is only used internally.
     public Template(String name,
        Reader reader,
        Configuration cfg,
        String encoding) 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.
    Method from freemarker.template.Template Summary:
    addImport,   addMacro,   addPrefixNSMapping,   containingElements,   createProcessingEnvironment,   createProcessingEnvironment,   dump,   dump,   getConfiguration,   getDefaultNS,   getEncoding,   getImports,   getMacros,   getName,   getNamespaceForPrefix,   getPlainTextTemplate,   getPrefixForNamespace,   getPrefixedName,   getRootTreeNode,   getSource,   process,   process,   process,   setEncoding,   toString
    Methods from freemarker.core.Configurable:
    clone,   getArithmeticEngine,   getBooleanFormat,   getBooleanFormat,   getCustomAttribute,   getCustomAttribute,   getCustomAttributeNames,   getDateFormat,   getDateTimeFormat,   getEnvironment,   getLocale,   getNumberFormat,   getObjectWrapper,   getOutputEncoding,   getParent,   getSetting,   getSettings,   getTemplateExceptionHandler,   getTimeFormat,   getTimeZone,   getURLEscapingCharset,   invalidSettingValueException,   isClassicCompatible,   removeCustomAttribute,   setArithmeticEngine,   setBooleanFormat,   setClassicCompatible,   setCustomAttribute,   setCustomAttribute,   setDateFormat,   setDateTimeFormat,   setLocale,   setNumberFormat,   setObjectWrapper,   setOutputEncoding,   setParent,   setSetting,   setSettings,   setSettings,   setStrictBeanModels,   setTemplateExceptionHandler,   setTimeFormat,   setTimeZone,   setURLEscapingCharset,   unknownSettingException
    Methods from java.lang.Object:
    equals,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
    Method from freemarker.template.Template Detail:
     public  void addImport(LibraryLoad ll) 
      Called by code internally to maintain a list of imports
     public  void addMacro(Macro macro) 
      Called by code internally to maintain a table of macros
     public  void addPrefixNSMapping(String prefix,
        String nsURI) 
      This is used internally.
     public TreePath containingElements(int column,
        int line) 
     public Environment createProcessingEnvironment(Object rootMap,
        Writer out) throws IOException, TemplateException 
      Same as createProcessingEnvironment(rootMap, out, null).
     public Environment createProcessingEnvironment(Object rootMap,
        Writer out,
        ObjectWrapper wrapper) throws IOException, 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
      
     public  void dump(PrintStream ps) 
      Dump the raw template in canonical form.
     public  void dump(Writer out) throws IOException 
      Dump the raw template in canonical form.
     public Configuration getConfiguration() 
      Returns the Configuration object associated with this template.
     public String getDefaultNS() 
     public String getEncoding() 
      Returns the character encoding used for reading included files.
     public List getImports() 
     public Map getMacros() 
     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.
     public String getNamespaceForPrefix(String prefix) 
     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.)
     public String getPrefixForNamespace(String nsURI) 
     public String getPrefixedName(String localName,
        String nsURI) 
     public TemplateElement getRootTreeNode() 
     public String getSource(int beginColumn,
        int beginLine,
        int endColumn,
        int endLine) 
      Returns the template source at the location specified by the coordinates given.
     public  void process(Object rootMap,
        Writer out) throws IOException, TemplateException 
      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.
     public  void process(Object rootMap,
        Writer out,
        ObjectWrapper wrapper) throws IOException, TemplateException 
      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.
     public  void process(Object rootMap,
        Writer out,
        ObjectWrapper wrapper,
        TemplateNodeModel rootNode) throws IOException, TemplateException 
      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.
     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.
     public String toString() 
      Returns a string representing the raw template text in canonical form.