public class Template extends Configurable
Typically, you will use Configuration.getTemplate(String)
to create/get Template
objects, so you
don't construct them directly. But you can also construct a template from a Reader
or a String
that
contains the template source code. But then it's important to know that while the resulting Template
is
efficient for later processing, creating a new Template
itself is relatively expensive. So try to re-use
Template
objects if possible. Configuration.getTemplate(String)
(and its overloads) does that
(caching Template
-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. If some templates need different settings that those coming from the
shared Configuration
, and you are using Configuration.getTemplate(String)
(or its overloads), then
use Configuration.setTemplateConfigurations(freemarker.cache.TemplateConfigurationFactory)
to achieve that.
Modifier and Type | Class and Description |
---|---|
static class |
Template.WrongEncodingException
Thrown by the
Template constructors that specify a non-null encoding whoch doesn't match the
encoding specified in the #ftl header of the template. |
Configurable.SettingValueAssignmentException, Configurable.UnknownSettingException
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
DEFAULT_NAMESPACE_PREFIX |
static java.lang.String |
NO_NS_PREFIX |
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, ATTEMPT_EXCEPTION_REPORTER_KEY, ATTEMPT_EXCEPTION_REPORTER_KEY_CAMEL_CASE, ATTEMPT_EXCEPTION_REPORTER_KEY_SNAKE_CASE, AUTO_FLUSH_KEY, AUTO_FLUSH_KEY_CAMEL_CASE, AUTO_FLUSH_KEY_SNAKE_CASE, AUTO_IMPORT_KEY, AUTO_IMPORT_KEY_CAMEL_CASE, AUTO_IMPORT_KEY_SNAKE_CASE, AUTO_INCLUDE_KEY, AUTO_INCLUDE_KEY_CAMEL_CASE, AUTO_INCLUDE_KEY_SNAKE_CASE, BOOLEAN_FORMAT_KEY, BOOLEAN_FORMAT_KEY_CAMEL_CASE, BOOLEAN_FORMAT_KEY_SNAKE_CASE, C_FORMAT_KEY, C_FORMAT_KEY_CAMEL_CASE, C_FORMAT_KEY_SNAKE_CASE, CLASSIC_COMPATIBLE_KEY, CLASSIC_COMPATIBLE_KEY_CAMEL_CASE, CLASSIC_COMPATIBLE_KEY_SNAKE_CASE, CUSTOM_DATE_FORMATS_KEY, CUSTOM_DATE_FORMATS_KEY_CAMEL_CASE, CUSTOM_DATE_FORMATS_KEY_SNAKE_CASE, CUSTOM_NUMBER_FORMATS_KEY, CUSTOM_NUMBER_FORMATS_KEY_CAMEL_CASE, CUSTOM_NUMBER_FORMATS_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, LAZY_AUTO_IMPORTS_KEY, LAZY_AUTO_IMPORTS_KEY_CAMEL_CASE, LAZY_AUTO_IMPORTS_KEY_SNAKE_CASE, LAZY_IMPORTS_KEY, LAZY_IMPORTS_KEY_CAMEL_CASE, LAZY_IMPORTS_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, TRUNCATE_BUILTIN_ALGORITHM_KEY, TRUNCATE_BUILTIN_ALGORITHM_KEY_CAMEL_CASE, TRUNCATE_BUILTIN_ALGORITHM_KEY_SNAKE_CASE, URL_ESCAPING_CHARSET_KEY, URL_ESCAPING_CHARSET_KEY_CAMEL_CASE, URL_ESCAPING_CHARSET_KEY_SNAKE_CASE, WRAP_UNCHECKED_EXCEPTIONS_KEY, WRAP_UNCHECKED_EXCEPTIONS_KEY_CAMEL_CASE, WRAP_UNCHECKED_EXCEPTIONS_KEY_SNAKE_CASE
Constructor and Description |
---|
Template(java.lang.String name,
java.io.Reader reader)
Deprecated.
This constructor uses the "default"
Configuration
instance, which can easily lead to erroneous, unpredictable behavior.
See more here... . |
Template(java.lang.String name,
java.io.Reader reader,
Configuration cfg)
|
Template(java.lang.String name,
java.io.Reader reader,
Configuration cfg,
java.lang.String encoding)
Convenience constructor for
Template(name, null,
reader, cfg, encoding) . |
Template(java.lang.String name,
java.lang.String sourceCode,
Configuration cfg)
Convenience constructor for
Template(name, new StringReader(reader), cfg) . |
Template(java.lang.String name,
java.lang.String sourceName,
java.io.Reader reader,
Configuration cfg)
Constructs a template from a character stream.
|
Template(java.lang.String name,
java.lang.String sourceName,
java.io.Reader reader,
Configuration cfg,
ParserConfiguration customParserConfiguration,
java.lang.String encoding)
Same as
Template(String, String, Reader, Configuration, String) , but also specifies a
TemplateConfiguration . |
Template(java.lang.String name,
java.lang.String sourceName,
java.io.Reader reader,
Configuration cfg,
java.lang.String encoding)
Same as
Template(String, String, Reader, Configuration) , but also specifies the template's encoding (not
recommended). |
Modifier and Type | Method and 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(java.lang.String prefix,
java.lang.String nsURI)
Deprecated.
Should only be used internally, and might will be removed later.
|
java.util.List |
containingElements(int column,
int line)
Deprecated.
Should only be used internally, and might will be removed later.
|
Environment |
createProcessingEnvironment(java.lang.Object dataModel,
java.io.Writer out)
|
Environment |
createProcessingEnvironment(java.lang.Object dataModel,
java.io.Writer out,
ObjectWrapper wrapper)
Creates a
Environment object, using this template, the data-model provided as
parameter. |
void |
dump(java.io.PrintStream ps)
Dump the raw template in canonical form.
|
void |
dump(java.io.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.
|
boolean |
getAutoEscaping()
Returns if the template actually uses auto-escaping (see
Configuration.setAutoEscapingPolicy(int) ). |
Configuration |
getConfiguration()
Returns the Configuration object associated with this template.
|
java.lang.Object |
getCustomLookupCondition()
Gets the custom lookup condition with which this template was found.
|
java.lang.String |
getDefaultNS() |
java.lang.String |
getEncoding()
The encoding that was (allegedly) used to read this template; also the the default character encoding used for
reading files included from this template.
|
java.util.List |
getImports()
Deprecated.
Should only be used internally, and might will be removed later.
|
int |
getInterpolationSyntax()
Returns the interpolation syntax the parser has used for this template.
|
java.util.Map |
getMacros()
Deprecated.
Should only be used internally, and might will be removed later.
|
java.lang.String |
getName()
The usually path-like (or URL-like) identifier of the template, or possibly
null for non-stored
templates. |
java.lang.String |
getNamespaceForPrefix(java.lang.String prefix) |
OutputFormat |
getOutputFormat()
Returns the output format (see
Configuration.setOutputFormat(OutputFormat) ) used for this template. |
ParserConfiguration |
getParserConfiguration()
Returns the
ParserConfiguration that was used for parsing this template. |
static Template |
getPlainTextTemplate(java.lang.String name,
java.lang.String content,
Configuration config)
|
static Template |
getPlainTextTemplate(java.lang.String name,
java.lang.String sourceName,
java.lang.String content,
Configuration config)
Creates (not "get"-s) a
Template that only contains a single block of static text, no dynamic content. |
java.lang.String |
getPrefixedName(java.lang.String localName,
java.lang.String nsURI) |
java.lang.String |
getPrefixForNamespace(java.lang.String nsURI) |
freemarker.core.TemplateElement |
getRootTreeNode()
Deprecated.
Should only be used internally, and might will be removed later.
|
java.lang.String |
getSource(int beginColumn,
int beginLine,
int endColumn,
int endLine)
Returns the template source at the location specified by the coordinates given, or
null if unavailable. |
java.lang.String |
getSourceName()
The name that was actually used to load this template from the
TemplateLoader (or from other custom
storage mechanism). |
void |
process(java.lang.Object dataModel,
java.io.Writer out)
Executes template, using the data-model provided, writing the generated output to the supplied
Writer . |
void |
process(java.lang.Object dataModel,
java.io.Writer out,
ObjectWrapper wrapper)
Like
process(Object, Writer) , but overrides the Configurable.getObjectWrapper() . |
void |
process(java.lang.Object dataModel,
java.io.Writer out,
ObjectWrapper wrapper,
TemplateNodeModel rootNode)
Like
process(Object, Writer) , but also sets a (XML-)node to be recursively processed by the template. |
void |
setCustomLookupCondition(java.lang.Object customLookupCondition)
Mostly only used internally; setter pair of
getCustomLookupCondition() . |
void |
setEncoding(java.lang.String encoding)
Deprecated.
Should only be used internally, and might will be removed later.
|
java.lang.String |
toString()
Returns a string representing the raw template
text in canonical form.
|
addAutoImport, addAutoInclude, clone, doAutoImportsAndIncludes, getArithmeticEngine, getAttemptExceptionReporter, getAutoFlush, getAutoImports, getAutoImportsWithoutFallback, getAutoIncludes, getAutoIncludesWithoutFallback, getBooleanFormat, getCFormat, getClassicCompatibleAsInt, getCorrectedNameForUnknownSetting, getCustomAttribute, getCustomAttributeNames, getCustomDateFormat, getCustomDateFormats, getCustomDateFormatsWithoutFallback, getCustomNumberFormat, getCustomNumberFormats, getCustomNumberFormatsWithoutFallback, getDateFormat, getDateTimeFormat, getEnvironment, getLazyAutoImports, getLazyImports, getLocale, getLogTemplateExceptions, getNewBuiltinClassResolver, getNumberFormat, getObjectWrapper, getOutputEncoding, getParent, getSetting, getSettingNames, getSettings, getShowErrorTips, getSQLDateAndTimeTimeZone, getTemplateExceptionHandler, getTimeFormat, getTimeZone, getTruncateBuiltinAlgorithm, getURLEscapingCharset, getWrapUncheckedExceptions, hasCustomFormats, invalidSettingValueException, isAPIBuiltinEnabled, isAPIBuiltinEnabledSet, isArithmeticEngineSet, isAttemptExceptionReporterSet, isAutoFlushSet, isAutoImportsSet, isAutoIncludesSet, isBooleanFormatSet, isCFormatSet, isClassicCompatible, isClassicCompatibleSet, isCustomDateFormatsSet, isCustomNumberFormatsSet, isDateFormatSet, isDateTimeFormatSet, isLazyAutoImportsSet, isLazyImportsSet, isLocaleSet, isLogTemplateExceptionsSet, isNewBuiltinClassResolverSet, isNumberFormatSet, isObjectWrapperSet, isOutputEncodingSet, isShowErrorTipsSet, isSQLDateAndTimeTimeZoneSet, isTemplateExceptionHandlerSet, isTimeFormatSet, isTimeZoneSet, isTruncateBuiltinAlgorithmSet, isURLEscapingCharsetSet, isWrapUncheckedExceptionsSet, parseAsImportList, parseAsList, parseAsSegmentedList, removeAutoImport, removeAutoInclude, removeCustomAttribute, setAPIBuiltinEnabled, setArithmeticEngine, setAttemptExceptionReporter, setAutoFlush, setAutoImports, setAutoIncludes, setBooleanFormat, setCFormat, setClassicCompatible, setClassicCompatibleAsInt, setCustomAttribute, setCustomDateFormats, setCustomNumberFormats, setDateFormat, setDateTimeFormat, setLazyAutoImports, setLazyImports, setLocale, setLogTemplateExceptions, setNewBuiltinClassResolver, setNumberFormat, setObjectWrapper, setOutputEncoding, setSetting, setSettings, setSettings, setShowErrorTips, setSQLDateAndTimeTimeZone, setStrictBeanModels, setTemplateExceptionHandler, setTimeFormat, setTimeZone, settingValueAssignmentException, setTruncateBuiltinAlgorithm, setURLEscapingCharset, setWrapUncheckedExceptions, unknownSettingException
public static final java.lang.String DEFAULT_NAMESPACE_PREFIX
public static final java.lang.String NO_NS_PREFIX
public Template(java.lang.String name, java.io.Reader reader, Configuration cfg) throws java.io.IOException
java.io.IOException
public Template(java.lang.String name, java.lang.String sourceCode, Configuration cfg) throws java.io.IOException
Template(name, new StringReader(reader), cfg)
.java.io.IOException
public Template(java.lang.String name, java.io.Reader reader, Configuration cfg, java.lang.String encoding) throws java.io.IOException
Template(name, null,
reader, cfg, encoding)
.java.io.IOException
public Template(java.lang.String name, java.lang.String sourceName, java.io.Reader reader, Configuration cfg) throws java.io.IOException
Template
instances instead of re-creating them from the
same source again and again. (and its overloads already do such reuse.
)name
- The path of the template file relatively to the (virtual) directory that you use to store the
templates (except if sourceName
differs from it). Shouldn't start with '/'
. Should use '/'
, not '\'
. Check
getName()
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; see TemplateLoader
), 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 via
Configuration.setDirectoryForTemplateLoading(java.io.File)
, then the template name will be
"forum/main.ftl"
. The name can be null
(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 the TemplateLoader
that knows what that
"physically" means).sourceName
- See getSourceName()
for the meaning. Can be null
, in which case
getSourceName()
will return the same as getName()
.reader
- The character stream to read from. It will always be closed (Reader.close()
) by
this method (this is for backward compatibility; later major versions may discontinue this behavior).
The Reader
need not be buffered, because this method ensures that it will be read in few
kilobyte chunks, not byte by byte.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 behavior. (See more here...
)java.io.IOException
public Template(java.lang.String name, java.lang.String sourceName, java.io.Reader reader, Configuration cfg, java.lang.String encoding) throws java.io.IOException
Template(String, String, Reader, Configuration)
, but also specifies the template's encoding (not
recommended).encoding
- This is the encoding that we are supposed to be using. At the first glance it's unnecessary because we
already have a Reader
(so decoding with the charset has already happened), however, if this is
non-null
and there's an #ftl
header with encoding
parameter, they must match,
or else a Template.WrongEncodingException
is thrown. Thus, it should be set if to decode the template,
we were using an encoding (a charset), otherwise it should be null
. It's also kept as
meta-info (returned by getEncoding()
). It also has an impact when #include
-ing or
#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.java.io.IOException
public Template(java.lang.String name, java.lang.String sourceName, java.io.Reader reader, Configuration cfg, ParserConfiguration customParserConfiguration, java.lang.String encoding) throws java.io.IOException
Template(String, String, Reader, Configuration, String)
, but also specifies a
TemplateConfiguration
. This is mostly meant to be used by FreeMarker internally, but advanced users might
still find this useful.customParserConfiguration
- Overrides the parsing related configuration settings of the Configuration
parameter; can be
null
. This is useful as the Configuration
is normally a singleton shared by all
templates, and so it's not good for specifying template-specific settings. (While Template
itself has methods to specify settings just for that template, those don't influence the parsing, and
you only have opportunity to call them after the parsing anyway.) This objects is often a
TemplateConfiguration
whose parent is the Configuration
parameter, and then it
practically just overrides some of the parser settings, as the others are inherited from the
Configuration
. Note that if this is a TemplateConfiguration
, you will also want to
call TemplateConfiguration.apply(Template)
on the resulting Template
so that
Configurable
settings will be set too, because this constructor only uses it as a
ParserConfiguration
.encoding
- Same as in Template(String, String, Reader, Configuration, String)
. When it's non-null
, it overrides the value coming from the TemplateConfiguration.getEncoding()
method of
the templateConfiguration
parameter.java.io.IOException
@Deprecated public Template(java.lang.String name, java.io.Reader reader) throws java.io.IOException
Configuration
instance, which can easily lead to erroneous, unpredictable behavior.
See more here...
.Template(name, reader, null)
.java.io.IOException
public static Template getPlainTextTemplate(java.lang.String name, java.lang.String content, Configuration config)
public static Template getPlainTextTemplate(java.lang.String name, java.lang.String sourceName, java.lang.String content, Configuration config)
Template
that only contains a single block of static text, no dynamic content.name
- See getName()
for more details.sourceName
- See getSourceName()
for more details. If null
, it will be the same as the name
.content
- the block of text that this template representsconfig
- the configuration to which this template belongspublic void process(java.lang.Object dataModel, java.io.Writer out) throws TemplateException, java.io.IOException
Writer
.
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.
dataModel
- the holder of the variables visible from the template (name-value pairs); usually a
Map<String, Object>
or a JavaBean (where the JavaBean properties will be the variables). Can
be any object that the ObjectWrapper
in use turns into a TemplateHashModel
. You can
also use an object that already implements TemplateHashModel
; in that case it won't be
wrapped. If it's null
, an empty data model is used.out
- The Writer
where the output of the template will go. Note that unless you have used
Configurable.setAutoFlush(boolean)
to disable this, Writer.flush()
will be called at
the when the template processing was finished. Writer.close()
is not called. Can't be
null
.TemplateException
- if an exception occurs during template processingjava.io.IOException
- if an I/O exception occurs during writing to the writer.public void process(java.lang.Object dataModel, java.io.Writer out, ObjectWrapper wrapper, TemplateNodeModel rootNode) throws TemplateException, java.io.IOException
process(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.rootNode
- The root node for recursive processing or null
.TemplateException
- if an exception occurs during template processingjava.io.IOException
- if an I/O exception occurs during writing to the writer.public void process(java.lang.Object dataModel, java.io.Writer out, ObjectWrapper wrapper) throws TemplateException, java.io.IOException
process(Object, Writer)
, but overrides the Configurable.getObjectWrapper()
.wrapper
- The ObjectWrapper
to be used instead of what Configurable.getObjectWrapper()
provides, or null
if you don't want to override that.TemplateException
java.io.IOException
public Environment createProcessingEnvironment(java.lang.Object dataModel, java.io.Writer out, ObjectWrapper wrapper) throws TemplateException, java.io.IOException
Environment
object, using this template, the data-model provided as
parameter. You have to call Environment.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 the Environment
after template processing. Otherwise using
process(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
dataModel
- the holder of the variables visible from all templates; see process(Object, Writer)
for
more details.wrapper
- The ObjectWrapper
to use to wrap objects into TemplateModel
instances. Normally you left it null
, in which case Configurable.getObjectWrapper()
will be
used.out
- The Writer
where the output of the template will go; see process(Object, Writer)
for
more details.Environment
object created for processing. Call Environment.process()
to process the
template.TemplateException
- if an exception occurs while setting up the Environment object.java.io.IOException
- if an exception occurs doing any auto-importspublic Environment createProcessingEnvironment(java.lang.Object dataModel, java.io.Writer out) throws TemplateException, java.io.IOException
TemplateException
java.io.IOException
public java.lang.String toString()
toString
in class java.lang.Object
public java.lang.String getName()
null
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 a TemplateLoader
used to load the backing resource (in simple cases; actually that name is
getSourceName()
, but see it there). Or, it can also be a name that was never used to load the template
(directly created with Template(String, Reader, Configuration)
). Even if the templates are stored
straightforwardly in files, this is relative to the base directory of the TemplateLoader
. 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. Use getSourceName()
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"
.
public java.lang.String getSourceName()
TemplateLoader
(or from other custom
storage mechanism). This is what should be shown in error messages as the error location. This is usually the
same as getName()
, except when localized lookup, template acquisition (*
step in the name), or
other TemplateLookupStrategy
transforms the requested name (getName()
) to a different final
TemplateLoader
-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 the name
, not
to the sourceName
.public Configuration getConfiguration()
public ParserConfiguration getParserConfiguration()
ParserConfiguration
that was used for parsing this template. This is most often the same
object as getConfiguration()
, but sometimes it's a TemplateConfiguration
, or something else.
It's never null
.@Deprecated public void setEncoding(java.lang.String encoding)
encoding
- The encoding that was used to read this template. When this template #include
-s or
#import
-s another template, by default it will use this encoding for those. For backward
compatibility, this can be null
, which will unset this setting.public java.lang.String getEncoding()
null
, in which case you are supposed to use
Configuration.getEncoding(Locale)
.public java.lang.Object getCustomLookupCondition()
customLookupCondition
parameter of Configuration.getTemplate(String, java.util.Locale, Object, String, boolean, boolean)
for
more explanation.public void setCustomLookupCondition(java.lang.Object customLookupCondition)
getCustomLookupCondition()
. 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 new Template
objects, like from
TemplateCache
.public int getActualTagSyntax()
Configuration.SQUARE_BRACKET_TAG_SYNTAX
or Configuration.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 maybe
Configuration.AUTO_DETECT_TAG_SYNTAX
.Configuration.setTagSyntax(int)
public int getInterpolationSyntax()
getActualTagSyntax()
).Configuration.LEGACY_INTERPOLATION_SYNTAX
,
Configuration.DOLLAR_INTERPOLATION_SYNTAX
, or
Configuration.SQUARE_BRACKET_INTERPOLATION_SYNTAX
.Configuration.setInterpolationSyntax(int)
public int getActualNamingConvention()
Configuration.LEGACY_NAMING_CONVENTION
or Configuration.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 maybe
Configuration.AUTO_DETECT_TAG_SYNTAX
.Configuration.setNamingConvention(int)
public OutputFormat getOutputFormat()
Configuration.setOutputFormat(OutputFormat)
) used for this template.
The output format of a template can come from various places, in order of increasing priority:
Configuration.getOutputFormat()
, ParserConfiguration.getOutputFormat()
(which is usually
provided by Configuration.getTemplateConfigurations()
) and the #ftl
header's output_format
option in the template.public boolean getAutoEscaping()
Configuration.setAutoEscapingPolicy(int)
). This value
is decided by the parser based on the actual OutputFormat
, and the auto-escaping enums, in order of
increasing priority: Configuration.getAutoEscapingPolicy()
, ParserConfiguration.getAutoEscapingPolicy()
(which is usually provided by Configuration.getTemplateConfigurations()
), and finally on the #ftl
header's auto_esc
option in the template.public void dump(java.io.PrintStream ps)
public void dump(java.io.Writer out) throws java.io.IOException
java.io.IOException
@Deprecated public void addMacro(freemarker.core.Macro macro)
@Deprecated public void addImport(freemarker.core.LibraryLoad ll)
public java.lang.String getSource(int beginColumn, int beginLine, int endColumn, int endLine)
null
if unavailable.
A strange legacy in the behavior of this method is that it replaces tab characters with spaces according the
value of getParserConfiguration()
/ParserConfiguration.getTabSize()
(which usually
comes from Configuration.getTabSize()
), because tab characters move the column number with more than
1 in error messages. However, if you set the tab size to 1, this method leaves the tab characters as is.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-basedTemplateObject.getSource()
@Deprecated public freemarker.core.TemplateElement getRootTreeNode()
@Deprecated public java.util.Map getMacros()
@Deprecated public java.util.List getImports()
@Deprecated public void addPrefixNSMapping(java.lang.String prefix, java.lang.String nsURI)
public java.lang.String getDefaultNS()
public java.lang.String getNamespaceForPrefix(java.lang.String prefix)
public java.lang.String getPrefixForNamespace(java.lang.String nsURI)
public java.lang.String getPrefixedName(java.lang.String localName, java.lang.String nsURI)
@Deprecated public java.util.List containingElements(int column, int line)
TemplateElement
s containing the given column and line numbers.