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.
Template
public Template(String name,
Reader reader)
throws IOException
This constructor uses the "default" Configuration
instance, which can easily lead to erroneous, unpredictable behaviour.
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.
Template
public Template(String name,
Reader reader,
Configuration cfg)
throws IOException
This is equivalent to Template(name, reader, cfg, null)
Template
public Template(String name,
Reader reader,
Configuration cfg,
String encoding)
throws IOException
Constructs a template from a character stream.
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.
addImport
public void addImport(LibraryLoad ll)
Called by code internally to maintain
a list of imports
addMacro
public void addMacro(Macro macro)
Called by code internally to maintain
a table of macros
addPrefixNSMapping
public void addPrefixNSMapping(String prefix,
String nsURI)
This is used internally.
containingElements
public TreePath containingElements(int column,
int line)
column
- the columnline
- the line
- an array of the elements containing the given column and line numbers.
createProcessingEnvironment
public Environment createProcessingEnvironment(Object rootMap,
Writer out)
throws TemplateException,
IOException
Same as createProcessingEnvironment(rootMap, out, null)
.
createProcessingEnvironment(Object rootMap, Writer out, ObjectWrapper wrapper)
createProcessingEnvironment
public Environment createProcessingEnvironment(Object rootMap,
Writer out,
ObjectWrapper wrapper)
throws TemplateException,
IOException
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
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
- the writer to output the text to.wrapper
- The object wrapper to use to wrap objects into
TemplateModel
instances. If null, the default wrapper retrieved
by Configurable.getObjectWrapper()
is used.
dump
public void dump(PrintStream ps)
Dump the raw template in canonical form.
dump
public void dump(Writer out)
throws IOException
Dump the raw template in canonical form.
getConfiguration
public Configuration getConfiguration()
Returns the Configuration object associated with this template.
getDefaultNS
public String getDefaultNS()
getEncoding
public String getEncoding()
Returns the character encoding used for reading included files.
getImports
public List getImports()
getMacros
public Map getMacros()
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.
getNamespaceForPrefix
public String getNamespaceForPrefix(String prefix)
- the NamespaceUri mapped to this prefix in this template. (Or null if there is none.)
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.)
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 representsconfig
- the configuration to which this template belongs
getPrefixForNamespace
public String getPrefixForNamespace(String nsURI)
- the prefix mapped to this nsURI in this template. (Or null if there is none.)
getPrefixedName
public String getPrefixedName(String localName,
String nsURI)
- 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.
getRootTreeNode
public TemplateElement getRootTreeNode()
- the root TemplateElement object.
getSource
public String getSource(int beginColumn,
int beginLine,
int endColumn,
int endLine)
Returns the template source at the location
specified by the coordinates given.
beginColumn
- the first column of the requested source, 1-basedbeginLine
- the first line of the requested source, 1-basedendColumn
- the last column of the requested source, 1-basedendLine
- the last line of the requested source, 1-based
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.
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.
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.
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
- the writer to output the text to.wrapper
- The object wrapper to use to wrap objects into
TemplateModel
instances. If null, the default wrapper retrieved
by Configurable.getObjectWrapper()
is used.
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.
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
- the writer to output the text to.wrapper
- The object wrapper to use to wrap objects into
TemplateModel
instances. If null, the default wrapper retrieved
by Configurable.getObjectWrapper()
is used.rootNode
- The root node for recursive processing, this may be null.
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.
toString
public String toString()
Returns a string representing the raw template
text in canonical form.