Class Template
- java.lang.Object
-
- freemarker.core.Configurable
-
- freemarker.template.Template
-
public class Template extends Configurable
Stores an already parsed template, ready to be processed (rendered) for unlimited times, possibly from multiple threads.
Typically, you will use
Configuration.getTemplate(String)
to create/getTemplate
objects, so you don't construct them directly. But you can also construct a template from aReader
or aString
that contains the template source code. But then it's important to know that while the resultingTemplate
is efficient for later processing, creating a newTemplate
itself is relatively expensive. So try to re-useTemplate
objects if possible.Configuration.getTemplate(String)
does that (cachingTemplate
-s) for you, but the constructor of course doesn't, so it's up to you to solve then.Objects of this class meant to be handled as immutable and thus thread-safe. However, it has some setter methods for changing FreeMarker settings. Those must not be used while the template is being processed, or if the template object is already accessible from multiple threads.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
Template.WrongEncodingException
Thrown by theTemplate
constructors that specify a non-null
encoding whoch doesn't match the encoding specified in the#ftl
header of the template.-
Nested classes/interfaces inherited from class freemarker.core.Configurable
Configurable.SettingValueAssignmentException, Configurable.UnknownSettingException
-
-
Field Summary
Fields Modifier and Type Field Description static String
DEFAULT_NAMESPACE_PREFIX
static String
NO_NS_PREFIX
-
Fields inherited from class freemarker.core.Configurable
API_BUILTIN_ENABLED_KEY, API_BUILTIN_ENABLED_KEY_CAMEL_CASE, API_BUILTIN_ENABLED_KEY_SNAKE_CASE, ARITHMETIC_ENGINE_KEY, ARITHMETIC_ENGINE_KEY_CAMEL_CASE, ARITHMETIC_ENGINE_KEY_SNAKE_CASE, AUTO_FLUSH_KEY, AUTO_FLUSH_KEY_CAMEL_CASE, AUTO_FLUSH_KEY_SNAKE_CASE, BOOLEAN_FORMAT_KEY, BOOLEAN_FORMAT_KEY_CAMEL_CASE, BOOLEAN_FORMAT_KEY_SNAKE_CASE, CLASSIC_COMPATIBLE_KEY, CLASSIC_COMPATIBLE_KEY_CAMEL_CASE, CLASSIC_COMPATIBLE_KEY_SNAKE_CASE, DATE_FORMAT_KEY, DATE_FORMAT_KEY_CAMEL_CASE, DATE_FORMAT_KEY_SNAKE_CASE, DATETIME_FORMAT_KEY, DATETIME_FORMAT_KEY_CAMEL_CASE, DATETIME_FORMAT_KEY_SNAKE_CASE, LOCALE_KEY, LOCALE_KEY_CAMEL_CASE, LOCALE_KEY_SNAKE_CASE, LOG_TEMPLATE_EXCEPTIONS_KEY, LOG_TEMPLATE_EXCEPTIONS_KEY_CAMEL_CASE, LOG_TEMPLATE_EXCEPTIONS_KEY_SNAKE_CASE, NEW_BUILTIN_CLASS_RESOLVER_KEY, NEW_BUILTIN_CLASS_RESOLVER_KEY_CAMEL_CASE, NEW_BUILTIN_CLASS_RESOLVER_KEY_SNAKE_CASE, NUMBER_FORMAT_KEY, NUMBER_FORMAT_KEY_CAMEL_CASE, NUMBER_FORMAT_KEY_SNAKE_CASE, OBJECT_WRAPPER_KEY, OBJECT_WRAPPER_KEY_CAMEL_CASE, OBJECT_WRAPPER_KEY_SNAKE_CASE, OUTPUT_ENCODING_KEY, OUTPUT_ENCODING_KEY_CAMEL_CASE, OUTPUT_ENCODING_KEY_SNAKE_CASE, SHOW_ERROR_TIPS_KEY, SHOW_ERROR_TIPS_KEY_CAMEL_CASE, SHOW_ERROR_TIPS_KEY_SNAKE_CASE, SQL_DATE_AND_TIME_TIME_ZONE_KEY, SQL_DATE_AND_TIME_TIME_ZONE_KEY_CAMEL_CASE, SQL_DATE_AND_TIME_TIME_ZONE_KEY_SNAKE_CASE, STRICT_BEAN_MODELS, STRICT_BEAN_MODELS_KEY, STRICT_BEAN_MODELS_KEY_CAMEL_CASE, STRICT_BEAN_MODELS_KEY_SNAKE_CASE, TEMPLATE_EXCEPTION_HANDLER_KEY, TEMPLATE_EXCEPTION_HANDLER_KEY_CAMEL_CASE, TEMPLATE_EXCEPTION_HANDLER_KEY_SNAKE_CASE, TIME_FORMAT_KEY, TIME_FORMAT_KEY_CAMEL_CASE, TIME_FORMAT_KEY_SNAKE_CASE, TIME_ZONE_KEY, TIME_ZONE_KEY_CAMEL_CASE, TIME_ZONE_KEY_SNAKE_CASE, URL_ESCAPING_CHARSET_KEY, URL_ESCAPING_CHARSET_KEY_CAMEL_CASE, URL_ESCAPING_CHARSET_KEY_SNAKE_CASE
-
-
Constructor Summary
Constructors Constructor Description Template(String name, Reader reader)
Deprecated.This constructor uses the "default"Configuration
instance, which can easily lead to erroneous, unpredictable behavior.Template(String name, Reader reader, Configuration cfg)
Template(String name, Reader reader, Configuration cfg, String encoding)
Deprecated.In most applications, useTemplate(String, Reader, Configuration)
instead, which doesn't specify the encoding.Template(String name, String sourceCode, Configuration cfg)
Convenience constructor forTemplate(name, new StringReader(reader), cfg)
.Template(String name, String sourceName, Reader reader, Configuration cfg)
Constructs a template from a character stream.Template(String name, String sourceName, Reader reader, Configuration cfg, String encoding)
Deprecated.In most applications, useTemplate(String, String, Reader, Configuration)
instead, which doesn't specify the encoding.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
addImport(freemarker.core.LibraryLoad ll)
Deprecated.Should only be used internally, and might will be removed later.void
addMacro(freemarker.core.Macro macro)
Deprecated.Should only be used internally, and might will be removed later.void
addPrefixNSMapping(String prefix, String nsURI)
Deprecated.Should only be used internally, and might will be removed later.TreePath
containingElements(int column, int line)
Deprecated.Should only be used internally, and might will be removed later.Environment
createProcessingEnvironment(Object dataModel, Writer out)
Environment
createProcessingEnvironment(Object dataModel, Writer out, ObjectWrapper wrapper)
Creates aEnvironment
object, using this template, the data-model provided as parameter.void
dump(PrintStream ps)
Dump the raw template in canonical form.void
dump(Writer out)
Dump the raw template in canonical form.int
getActualNamingConvention()
Returns the naming convention the parser has chosen for this template.int
getActualTagSyntax()
Returns the tag syntax the parser has chosen for this template.Configuration
getConfiguration()
Returns the Configuration object associated with this template.Object
getCustomLookupCondition()
Gets the custom lookup condition with which this template was found.String
getDefaultNS()
String
getEncoding()
Returns the default character encoding used for reading included files.List
getImports()
Deprecated.Should only be used internally, and might will be removed later.Map
getMacros()
Deprecated.Should only be used internally, and might will be removed later.String
getName()
The usually path-like (or URL-like) identifier of the template, or possiblynull
for non-stored templates.String
getNamespaceForPrefix(String prefix)
static Template
getPlainTextTemplate(String name, String content, Configuration config)
static Template
getPlainTextTemplate(String name, String sourceName, String content, Configuration config)
Creates aTemplate
that only contains a single block of static text, no dynamic content.String
getPrefixedName(String localName, String nsURI)
String
getPrefixForNamespace(String nsURI)
freemarker.core.TemplateElement
getRootTreeNode()
Deprecated.Should only be used internally, and might will be removed later.String
getSource(int beginColumn, int beginLine, int endColumn, int endLine)
Returns the template source at the location specified by the coordinates given, ornull
if unavailable.String
getSourceName()
The name that was actually used to load this template from theTemplateLoader
(or from other custom storage mechanism).void
process(Object dataModel, Writer out)
Executes template, using the data-model provided, writing the generated output to the suppliedWriter
.void
process(Object dataModel, Writer out, ObjectWrapper wrapper)
Likeprocess(Object, Writer)
, but overrides theConfigurable.getObjectWrapper()
.void
process(Object dataModel, Writer out, ObjectWrapper wrapper, TemplateNodeModel rootNode)
Likeprocess(Object, Writer)
, but also sets a (XML-)node to be recursively processed by the template.void
setCustomLookupCondition(Object customLookupCondition)
Mostly only used internally; setter pair ofgetCustomLookupCondition()
.void
setEncoding(String encoding)
Deprecated.Should only be used internally, and might will be removed later.String
toString()
Returns a string representing the raw template text in canonical form.-
Methods inherited from class freemarker.core.Configurable
clone, doAutoImportsAndIncludes, getArithmeticEngine, getAutoFlush, getBooleanFormat, getClassicCompatibleAsInt, getCorrectedNameForUnknownSetting, getCustomAttribute, getCustomAttributeNames, getDateFormat, getDateTimeFormat, getEnvironment, getLocale, getLogTemplateExceptions, getNewBuiltinClassResolver, getNumberFormat, getObjectWrapper, getOutputEncoding, getParent, getSetting, getSettings, getShowErrorTips, getSQLDateAndTimeTimeZone, getTemplateExceptionHandler, getTimeFormat, getTimeZone, getURLEscapingCharset, invalidSettingValueException, isAPIBuiltinEnabled, isClassicCompatible, parseAsImportList, parseAsList, parseAsSegmentedList, removeCustomAttribute, setAPIBuiltinEnabled, setArithmeticEngine, setAutoFlush, setBooleanFormat, setClassicCompatible, setClassicCompatibleAsInt, setCustomAttribute, setDateFormat, setDateTimeFormat, setLocale, setLogTemplateExceptions, setNewBuiltinClassResolver, setNumberFormat, setObjectWrapper, setOutputEncoding, setSetting, setSettings, setSettings, setShowErrorTips, setSQLDateAndTimeTimeZone, setStrictBeanModels, setTemplateExceptionHandler, setTimeFormat, setTimeZone, settingValueAssignmentException, setURLEscapingCharset, unknownSettingException
-
-
-
-
Field Detail
-
DEFAULT_NAMESPACE_PREFIX
public static final String DEFAULT_NAMESPACE_PREFIX
- See Also:
- Constant Field Values
-
NO_NS_PREFIX
public static final String NO_NS_PREFIX
- See Also:
- Constant Field Values
-
-
Constructor Detail
-
Template
public Template(String name, Reader reader, Configuration cfg) throws IOException
- Throws:
IOException
-
Template
public Template(String name, String sourceCode, Configuration cfg) throws IOException
Convenience constructor forTemplate(name, new StringReader(reader), cfg)
.- Throws:
IOException
- Since:
- 2.3.20
-
Template
public Template(String name, Reader reader, Configuration cfg, String encoding) throws IOException
Deprecated.In most applications, useTemplate(String, Reader, Configuration)
instead, which doesn't specify the encoding.Convenience constructor forTemplate(name, null, reader, cfg, encoding)
.- Throws:
IOException
-
Template
public Template(String name, String sourceName, Reader reader, Configuration cfg) throws IOException
Constructs a template from a character stream. Note that this is a relatively expensive operation; where higher performance matters, you should re-use (cache)Template
instances instead of re-creating them from the same source again and again. (and its overloads already do such reuse.
)- Parameters:
name
- The path of the template file relatively to the (virtual) directory that you use to store the templates (except ifsourceName
differs from it). Shouldn't start with'/'
. Should use'/'
, not'\'
. CheckgetName()
to see how the name will be used. The name should be independent of the actual storage mechanism and physical location as far as possible. Even when the templates are stored straightforwardly in real files (they often aren't; seeTemplateLoader
), the name shouldn't be an absolute file path. Like if the template is stored in"/www/templates/forum/main.ftl"
, and you are using"/www/templates/"
as the template root directory viaConfiguration.setDirectoryForTemplateLoading(java.io.File)
, then the template name will be"forum/main.ftl"
. The name can benull
(should be used for template made on-the-fly instead of being loaded from somewhere), in which case relative paths in it will be relative to the template root directory (and here again, it's theTemplateLoader
that knows what that "physically" means).sourceName
- SeegetSourceName()
for the meaning. Can benull
, in which casegetSourceName()
will return the same asgetName()
.reader
- The character stream to read from. It will always be closed (Reader.close()
) by this method.cfg
- The Configuration object that this Template is associated with. If this isnull
, the "default"Configuration
object is used, which is highly discouraged, because it can easily lead to erroneous, unpredictable behavior. (See morehere...
)- Throws:
IOException
- Since:
- 2.3.22
-
Template
public Template(String name, String sourceName, Reader reader, Configuration cfg, String encoding) throws IOException
Deprecated.In most applications, useTemplate(String, String, Reader, Configuration)
instead, which doesn't specify the encoding.Same asTemplate(String, String, Reader, Configuration)
, but also specifies the template's encoding (not recommended).- Parameters:
encoding
- This is the encoding that we are supposed to be using. But it's not really necessary because we have aReader
which is already decoded, but it's kept as meta-info. It also has an impact when#include
-ing/#import
-ing another template from this template, as its default encoding will be this. But this behavior of said directives is considered to be harmful, and will be probably phased out. Until that, it's better to leave this onnull
, so that the encoding will come from theConfiguration
. Note that if this is non-null
and there's an#ftl
header with encoding, they must match, or else aTemplate.WrongEncodingException
is thrown.- Throws:
IOException
- Since:
- 2.3.22
-
Template
public Template(String name, Reader reader) throws IOException
Deprecated.This constructor uses the "default"Configuration
instance, which can easily lead to erroneous, unpredictable behavior. See morehere...
.Equivalent toTemplate(name, reader, null)
.- Throws:
IOException
-
-
Method Detail
-
getPlainTextTemplate
public static Template getPlainTextTemplate(String name, String content, Configuration config)
-
getPlainTextTemplate
public static Template getPlainTextTemplate(String name, String sourceName, String content, Configuration config)
Creates aTemplate
that only contains a single block of static text, no dynamic content.- Parameters:
name
- SeegetName()
for more details.sourceName
- SeegetSourceName()
for more details. Ifnull
, it will be the same as thename
.content
- the block of text that this template representsconfig
- the configuration to which this template belongs- Since:
- 2.3.22
-
process
public void process(Object dataModel, Writer out) throws TemplateException, IOException
Executes template, using the data-model provided, writing the generated output to the suppliedWriter
.For finer control over the runtime environment setup, such as per-HTTP-request configuring of FreeMarker settings, you may need to use
createProcessingEnvironment(Object, Writer)
instead.- Parameters:
dataModel
- the holder of the variables visible from the template (name-value pairs); usually aMap<String, Object>
or a JavaBean (where the JavaBean properties will be the variables). Can be any object that theObjectWrapper
in use turns into aTemplateHashModel
. You can also use an object that already implementsTemplateHashModel
; in that case it won't be wrapped. If it'snull
, an empty data model is used.out
- TheWriter
where the output of the template will go. Note that unless you have usedConfigurable.setAutoFlush(boolean)
to disable this,Writer.flush()
will be called at the when the template processing was finished.Writer.close()
is not called.- Throws:
TemplateException
- if an exception occurs during template processingIOException
- if an I/O exception occurs during writing to the writer.
-
process
public void process(Object dataModel, Writer out, ObjectWrapper wrapper, TemplateNodeModel rootNode) throws TemplateException, IOException
Likeprocess(Object, Writer)
, but also sets a (XML-)node to be recursively processed by the template. That node is accessed in the template with .node, #recurse, etc. See the Declarative XML Processing as a typical example of recursive node processing.- Parameters:
rootNode
- The root node for recursive processing ornull
.- Throws:
TemplateException
- if an exception occurs during template processingIOException
- if an I/O exception occurs during writing to the writer.
-
process
public void process(Object dataModel, Writer out, ObjectWrapper wrapper) throws TemplateException, IOException
Likeprocess(Object, Writer)
, but overrides theConfigurable.getObjectWrapper()
.- Parameters:
wrapper
- TheObjectWrapper
to be used instead of whatConfigurable.getObjectWrapper()
provides, ornull
if you don't want to override that.- Throws:
TemplateException
IOException
-
createProcessingEnvironment
public Environment createProcessingEnvironment(Object dataModel, Writer out, ObjectWrapper wrapper) throws TemplateException, IOException
Creates aEnvironment
object, using this template, the data-model provided as parameter. You have to callEnvironment.process()
on the return value 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 theEnvironment
after template processing. Otherwise usingprocess(Object, Writer)
is simpler.Example:
Environment env = myTemplate.createProcessingEnvironment(root, out, null); env.process();
The above 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.setLocale(myUsersPreferredLocale); env.setTimeZone(myUsersPreferredTimezone); env.process(); // output is rendered here TemplateModel x = env.getVariable("x"); // read back a variable set by the template
- Parameters:
dataModel
- the holder of the variables visible from all templates; seeprocess(Object, Writer)
for more details.wrapper
- TheObjectWrapper
to use to wrap objects intoTemplateModel
instances. Normally you left itnull
, in which caseConfigurable.getObjectWrapper()
will be used.out
- TheWriter
where the output of the template will go; seeprocess(Object, Writer)
for more details.- Returns:
- the
Environment
object created for processing. CallEnvironment.process()
to process the template. - Throws:
TemplateException
- if an exception occurs while setting up the Environment object.IOException
- if an exception occurs doing any auto-imports
-
createProcessingEnvironment
public Environment createProcessingEnvironment(Object dataModel, Writer out) throws TemplateException, IOException
- Throws:
TemplateException
IOException
-
toString
public String toString()
Returns a string representing the raw template text in canonical form.
-
getName
public String getName()
The usually path-like (or URL-like) identifier of the template, or possiblynull
for non-stored templates. It usually looks like a relative UN*X path; it should use/
, not\
, and shouldn't start with/
(but there are no hard guarantees). It's not a real path in a file-system, it's just a name that aTemplateLoader
used to load the backing resource (in simple cases; actually that name isgetSourceName()
, but see it there). Or, it can also be a name that was never used to load the template (directly created withTemplate(String, Reader, Configuration)
). Even if the templates are stored straightforwardly in files, this is relative to the base directory of theTemplateLoader
. So it really could be anything, except that it has importance in these situations:Relative paths to other templates in this template will be resolved relatively to the directory part of this. Like if the template name is
"foo/this.ftl"
, then<#include "other.ftl">
gets the template with name"foo/other.ftl"
.You should not use this name to indicate error locations, or to find the actual templates in general, because localized lookup, acquisition and other lookup strategies can transform names before they get to the
TemplateLoader
(the template storage) mechanism. UsegetSourceName()
for these purposes.Some frameworks use URL-like template names like
"someSchema://foo/bar.ftl"
. FreeMarker understands this notation, so an absolute path like"/baaz.ftl"
in that template will be resolved too"someSchema://baaz.ftl"
.
-
getSourceName
public String getSourceName()
The name that was actually used to load this template from theTemplateLoader
(or from other custom storage mechanism). This is what should be shown in error messages as the error location. This is usually the same asgetName()
, except when localized lookup, template acquisition (*
step in the name), or otherTemplateLookupStrategy
transforms the requested name (getName()
) to a different finalTemplateLoader
-level name. For example, when you get a template with name"foo.ftl"
then because of localized lookup, it's possible that something like"foo_en.ftl"
will be loaded behind the scenes. While the template name will be still the same as the requested template name ("foo.ftl"
), errors should point to"foo_de.ftl"
. Note that relative paths are always resolved relatively to thename
, not to thesourceName
.- Since:
- 2.3.22
-
getConfiguration
public Configuration getConfiguration()
Returns the Configuration object associated with this template.
-
setEncoding
public void setEncoding(String encoding)
Deprecated.Should only be used internally, and might will be removed later.
-
getEncoding
public String getEncoding()
Returns the default character encoding used for reading included files.
-
getCustomLookupCondition
public Object getCustomLookupCondition()
Gets the custom lookup condition with which this template was found. See thecustomLookupCondition
parameter ofConfiguration.getTemplate(String, java.util.Locale, Object, String, boolean, boolean)
for more explanation.- Since:
- 2.3.22
-
setCustomLookupCondition
public void setCustomLookupCondition(Object customLookupCondition)
Mostly only used internally; setter pair ofgetCustomLookupCondition()
. This meant to be called directly after instantiating the template with its constructor, after a successfull lookup that used this condition. So this should only be called from code that deals with creating newTemplate
objects, like fromTemplateCache
.- Since:
- 2.3.22
-
getActualTagSyntax
public int getActualTagSyntax()
Returns the tag syntax the parser has chosen for this template. If the syntax could be determined, it'sConfiguration.SQUARE_BRACKET_TAG_SYNTAX
orConfiguration.ANGLE_BRACKET_TAG_SYNTAX
. If the syntax couldn't be determined (like because there was no tags in the template, or it was a plain text template), this returns whatever the default is in the current configuration, so it's maybeConfiguration.AUTO_DETECT_TAG_SYNTAX
.- Since:
- 2.3.20
-
getActualNamingConvention
public int getActualNamingConvention()
Returns the naming convention the parser has chosen for this template. If it could be determined, it'sConfiguration.LEGACY_NAMING_CONVENTION
orConfiguration.CAMEL_CASE_NAMING_CONVENTION
. If it couldn't be determined (like because there no identifier that's part of the template language was used where the naming convention matters), this returns whatever the default is in the current configuration, so it's maybeConfiguration.AUTO_DETECT_TAG_SYNTAX
.- Since:
- 2.3.23
-
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.- Throws:
IOException
-
addMacro
public void addMacro(freemarker.core.Macro macro)
Deprecated.Should only be used internally, and might will be removed later.Called by code internally to maintain a table of macros
-
addImport
public void addImport(freemarker.core.LibraryLoad ll)
Deprecated.Should only be used internally, and might will be removed later.Called by code internally to maintain a list of imports
-
getSource
public String getSource(int beginColumn, int beginLine, int endColumn, int endLine)
Returns the template source at the location specified by the coordinates given, ornull
if unavailable.- Parameters:
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- See Also:
TemplateObject.getSource()
-
getRootTreeNode
public freemarker.core.TemplateElement getRootTreeNode()
Deprecated.Should only be used internally, and might will be removed later.
-
getMacros
public Map getMacros()
Deprecated.Should only be used internally, and might will be removed later.
-
getImports
public List getImports()
Deprecated.Should only be used internally, and might will be removed later.
-
addPrefixNSMapping
public void addPrefixNSMapping(String prefix, String nsURI)
Deprecated.Should only be used internally, and might will be removed later.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 TreePath containingElements(int column, int line)
Deprecated.Should only be used internally, and might will be removed later.- Returns:
- an array of the
TemplateElement
s containing the given column and line numbers.
-
-