public final class Environment extends Configurable
Data models that need to access the Environment
object that represents the template processing on the current thread can use
the getCurrentEnvironment()
method.
If you need to modify or read this object before or after the process
call, use Template.createProcessingEnvironment(Object rootMap, Writer out, ObjectWrapper wrapper)
Modifier and Type | Class and Description |
---|---|
class |
Environment.Namespace |
Configurable.SettingValueAssignmentException, Configurable.UnknownSettingException
API_BUILTIN_ENABLED_KEY, ARITHMETIC_ENGINE_KEY, AUTO_FLUSH_KEY, BOOLEAN_FORMAT_KEY, CLASSIC_COMPATIBLE_KEY, DATE_FORMAT_KEY, DATETIME_FORMAT_KEY, LOCALE_KEY, LOG_TEMPLATE_EXCEPTIONS_KEY, NEW_BUILTIN_CLASS_RESOLVER_KEY, NUMBER_FORMAT_KEY, OBJECT_WRAPPER_KEY, OUTPUT_ENCODING_KEY, SHOW_ERROR_TIPS_KEY, SQL_DATE_AND_TIME_TIME_ZONE_KEY, STRICT_BEAN_MODELS, STRICT_BEAN_MODELS_KEY, TEMPLATE_EXCEPTION_HANDLER_KEY, TIME_FORMAT_KEY, TIME_ZONE_KEY, URL_ESCAPING_CHARSET_KEY
Constructor and Description |
---|
Environment(Template template,
TemplateHashModel rootDataModel,
Writer out) |
Modifier and Type | Method and Description |
---|---|
Object |
__getitem__(String key)
A hook that Jython uses.
|
void |
__setitem__(String key,
Object o)
A hook that Jython uses.
|
boolean |
applyEqualsOperator(TemplateModel leftValue,
TemplateModel rightValue)
Compares two
TemplateModel -s according the rules of the FTL "==" operator. |
boolean |
applyEqualsOperatorLenient(TemplateModel leftValue,
TemplateModel rightValue)
Compares two
TemplateModel -s according the rules of the FTL "==" operator, except that if the two types
are incompatible, they are treated as non-equal instead of throwing an exception. |
boolean |
applyGreaterThanOperator(TemplateModel leftValue,
TemplateModel rightValue)
Compares two
TemplateModel -s according the rules of the FTL ">" operator. |
boolean |
applyLessThanOperator(TemplateModel leftValue,
TemplateModel rightValue)
Compares two
TemplateModel -s according the rules of the FTL "<" operator. |
boolean |
applyLessThanOrEqualsOperator(TemplateModel leftValue,
TemplateModel rightValue)
Compares two
TemplateModel -s according the rules of the FTL "<" operator. |
boolean |
applyWithGreaterThanOrEqualsOperator(TemplateModel leftValue,
TemplateModel rightValue)
Compares two
TemplateModel -s according the rules of the FTL ">=" operator. |
NumberFormat |
getCNumberFormat()
Returns the
NumberFormat used for the c built-in. |
Configuration |
getConfiguration() |
DirectiveCallPlace |
getCurrentDirectiveCallPlace()
Gets the currently executing custom directive's call place information, or
null if there's no
executing custom directive. |
static Environment |
getCurrentEnvironment()
Retrieves the environment object associated with the current
thread.
|
Environment.Namespace |
getCurrentNamespace()
Returns the current namespace.
|
TemplateNodeModel |
getCurrentVisitorNode() |
TemplateHashModel |
getDataModel()
Returns the data-model (also known as the template context in some other template engines).
|
String |
getDefaultNS() |
Environment.Namespace |
getGlobalNamespace()
Returns the name-space that contains the globally visible non-data-model variables
(usually created with
<#global ...> ). |
TemplateModel |
getGlobalVariable(String name)
Returns the globally visible variable of the given name (or null).
|
TemplateHashModel |
getGlobalVariables()
Returns the read-only hash of globally visible variables.
|
Set |
getKnownVariableNames()
Returns a set of variable names that are known at the time of call.
|
TemplateModel |
getLocalVariable(String name)
Returns the loop or macro local variable corresponding to this
variable name.
|
Environment.Namespace |
getMainNamespace()
Returns the main namespace.
|
Template |
getMainTemplate()
Returns the topmost
Template , with other words, the one for which this Environment was created. |
Environment.Namespace |
getNamespace(String name)
Returns the name-space for the name if exists, or null.
|
String |
getNamespaceForPrefix(String prefix) |
Writer |
getOut() |
String |
getPrefixForNamespace(String nsURI) |
Template |
getTemplate()
Deprecated.
Use
getMainTemplate() instead (or getCurrentNamespace() and then
Environment.Namespace.getTemplate() ); the value returned by this method is often not what you expect when
it comes to macro/function invocations. |
Template |
getTemplateForImporting(String name)
Gets a template for importing; used with
importLib(Template importedTemplate, String namespace) . |
Template |
getTemplateForInclusion(String name,
String encoding,
boolean parse)
Same as
getTemplateForInclusion(String, String, boolean, boolean) with false
ignoreMissign argument. |
Template |
getTemplateForInclusion(String name,
String encoding,
boolean parseAsFTL,
boolean ignoreMissing)
Gets a template for inclusion; used for implementing
include(Template includedTemplate) . |
TemplateModel |
getVariable(String name)
Returns the variable that is visible in this context.
|
Environment.Namespace |
importLib(String name,
String namespace)
Emulates
import directive, except that name must be tempate
root relative. |
Environment.Namespace |
importLib(Template loadedTemplate,
String namespace)
Emulates
import directive. |
void |
include(String name,
String encoding,
boolean parse)
Emulates
include directive, except that name must be tempate
root relative. |
void |
include(Template includedTemplate)
Processes a Template in the context of this
Environment , including its
output in the Environment 's Writer. |
boolean |
isInAttemptBlock()
Tells if we are inside an #attempt block (but before #recover).
|
void |
outputInstructionStack(PrintWriter pw)
Prints the current FTL stack trace.
|
void |
process()
Processes the template to which this environment belongs to.
|
void |
setCurrentVisitorNode(TemplateNodeModel node)
sets TemplateNodeModel as the current visitor node.
|
void |
setDateFormat(String dateFormat)
Sets the format used to convert
Date -s to string-s that are date (no time part) values,
also the format that someString?date will use to parse strings. |
void |
setDateTimeFormat(String dateTimeFormat)
Sets the format used to convert
Date -s to string-s that are date-time (timestamp) values,
also the format that someString?datetime will use to parse strings. |
void |
setGlobalVariable(String name,
TemplateModel model)
Sets a variable that is visible globally.
|
void |
setLocale(Locale locale)
Sets the default locale used for number and date formatting (among others), also the locale used for searching
localized template variations when no locale was explicitly requested.
|
void |
setLocalVariable(String name,
TemplateModel model)
Sets a local variable (one effective only during a macro invocation).
|
void |
setNumberFormat(String formatName)
Sets the default number format used to convert numbers to strings.
|
void |
setOut(Writer out) |
void |
setOutputEncoding(String outputEncoding)
Informs FreeMarker about the charset used for the output.
|
void |
setSQLDateAndTimeTimeZone(TimeZone timeZone)
Sets the time zone used when dealing with
java.sql.Date and
java.sql.Time values. |
void |
setTemplateExceptionHandler(TemplateExceptionHandler templateExceptionHandler)
Sets the exception handler used to handle exceptions occurring inside templates.
|
void |
setTimeFormat(String timeFormat)
Sets the format used to convert
Date -s to string-s that are time (no date part) values,
also the format that someString?time will use to parse strings. |
void |
setTimeZone(TimeZone timeZone)
Sets the time zone to use when formatting date/time values.
|
void |
setURLEscapingCharset(String urlEscapingCharset)
Sets the URL escaping charset.
|
void |
setVariable(String name,
TemplateModel model)
Sets a variable in the current namespace.
|
String |
toFullTemplateName(String baseName,
String targetName)
Resolves a reference to a template (like the one used in
#include or #import ), assuming a base
name. |
void |
visit(freemarker.core.TemplateElement element,
TemplateDirectiveModel directiveModel,
Map args,
List bodyParameterNames) |
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, setLogTemplateExceptions, setNewBuiltinClassResolver, setObjectWrapper, setSetting, setSettings, setSettings, setShowErrorTips, setStrictBeanModels, settingValueAssignmentException, unknownSettingException
public Environment(Template template, TemplateHashModel rootDataModel, Writer out)
public static Environment getCurrentEnvironment()
public Template getTemplate()
getMainTemplate()
instead (or getCurrentNamespace()
and then
Environment.Namespace.getTemplate()
); the value returned by this method is often not what you expect when
it comes to macro/function invocations.Configurable.getParent()
. If Configuration.getIncompatibleImprovements()
is
at least 2.3.22, then that will be the same as getMainTemplate()
. Otherwise the returned value follows
the Environment
parent switchings that occur at #include
/#import
and #nested
directive calls, that is, it's not very meaningful outside FreeMarker internals.public Template getMainTemplate()
Template
, with other words, the one for which this Environment
was created.
That template will never change, like #include
or macro calls don't change it.getCurrentNamespace()
public DirectiveCallPlace getCurrentDirectiveCallPlace()
null
if there's no
executing custom directive. This method currently only works calls made from templates with the <@...>
syntax. This should only be called from the TemplateDirectiveModel
that was invoked with <@...>
,
otherwise it's return value is not defined by this API (it's usually null
).public void process() throws TemplateException, IOException
TemplateException
IOException
public void visit(freemarker.core.TemplateElement element, TemplateDirectiveModel directiveModel, Map args, List bodyParameterNames) throws TemplateException, IOException
TemplateException
IOException
public boolean isInAttemptBlock()
TemplateExceptionHandler
-s, as then they may don't want to print the error to the output, as
#attempt will roll it back anyway.public void setTemplateExceptionHandler(TemplateExceptionHandler templateExceptionHandler)
Configurable
TemplateExceptionHandler.DEBUG_HANDLER
. The recommended values are:
TemplateExceptionHandler.RETHROW_HANDLER
TemplateExceptionHandler.HTML_DEBUG_HANDLER
TemplateExceptionHandler.DEBUG_HANDLER
All of these will let the exception propagate further, so that you can catch it around
Template.process(Object, Writer)
for example. The difference is in what they print on the output before
they do that.
Note that the TemplateExceptionHandler
is not meant to be used for generating HTTP error pages.
Neither is it meant to be used to roll back the printed output. These should be solved outside template
processing when the exception raises from Template.process
.
TemplateExceptionHandler
meant to be used if you want to include special content in the template
output, or if you want to suppress certain exceptions.
setTemplateExceptionHandler
in class Configurable
public void setLocale(Locale locale)
Configurable
setLocale
in class Configurable
Configuration.getTemplate(String, Locale)
public void setTimeZone(TimeZone timeZone)
Configurable
TimeZone.getDefault()
), regardless of the "locale" FreeMarker setting,
so in a server application you probably want to set it explicitly in the Environment
to match the
preferred time zone of target audience (like the Web page visitor).
If you or the templates set the time zone, you should probably also set
Configurable.setSQLDateAndTimeTimeZone(TimeZone)
!
setTimeZone
in class Configurable
Configurable.setSQLDateAndTimeTimeZone(TimeZone)
public void setSQLDateAndTimeTimeZone(TimeZone timeZone)
Configurable
java.sql.Date
and
java.sql.Time
values. It defaults to null
for backward compatibility, but in most
application this should be set to the JVM default time zone (server default time zone), because that's what
most JDBC drivers will use when constructing the java.sql.Date
and
java.sql.Time
values. If this setting is null
, FreeMarker will use the value of
(Configurable.getTimeZone()
) for java.sql.Date
and java.sql.Time
values,
which often gives bad results.
This setting doesn't influence the formatting of other kind of values (like of
java.sql.Timestamp
or plain java.util.Date
values).
To decide what value you need, a few things has to be understood:
Date
and its subclasses store (milliseconds since
the epoch). Obviously, this is impossible to do. So JDBC just chooses a physical time which, when rendered
with the JVM default time zone, will give the same field values as those stored
in the database. (Actually, you can give JDBC a calendar, and so it can use other time zones too, but most
application won't care using those overloads.) For example, assume that the system time zone is GMT+02:00.
Then, 2014-07-12 in the database will be translated to physical time 2014-07-11 22:00:00 UTC, because that
rendered in GMT+02:00 gives 2014-07-12 00:00:00. Similarly, 11:57:00 in the database will be translated to
physical time 1970-01-01 09:57:00 UTC. Thus, the physical time stored in the returned value depends on the
default system time zone of the JDBC client, not just on the content in the database. (This used to be the
default behavior of ORM-s, like Hibernate, too.)
time_zone
FreeMarker configuration setting sets the time zone used for the
template output. For example, when a web page visitor has a preferred time zone, the web application framework
may calls setTimeZone(TimeZone)
with that time zone. Thus, the visitor will
see java.sql.Timestamp
and plain java.util.Date
values as
they look in his own time zone. While
this is desirable for those types, as they meant to represent physical points on the time line, this is not
necessarily desirable for date-only and time-only values. When sql_date_and_time_time_zone
is
null
, time_zone
is used for rendering all kind of date/time/dateTime values, including
java.sql.Date
and java.sql.Time
, and then if, for example,
time_zone
is GMT+00:00, the
values from the earlier examples will be shown as 2014-07-11 (one day off) and 09:57:00 (2 hours off). While
those are the time zone correct renderings, those values probably was meant to shown "as is".
java.sql.Timestamp
too. FreeMarker assumes that you have set up your
application so that time stamps coming from the database go through the necessary conversion to store the
correct distance from the epoch (1970-01-01 00:00:00 UTC), as requested by Date
. In that case
the time stamp can be safely rendered in different time zones, and thus it needs no special treatment.
setSQLDateAndTimeTimeZone
in class Configurable
timeZone
- Maybe null
, in which case java.sql.Date
and
java.sql.Time
values will be formatted in the time zone returned by
Configurable.getTimeZone()
.
(Note that since null
is an allowed value for this setting, it will not cause
Configurable.getSQLDateAndTimeTimeZone()
to fall back to the parent configuration.)Configurable.setTimeZone(TimeZone)
public void setURLEscapingCharset(String urlEscapingCharset)
Configurable
null
), the output encoding
(Configurable.setOutputEncoding(String)
) will be used for URL escaping.
Defaults to null
.setURLEscapingCharset
in class Configurable
public void setOutputEncoding(String outputEncoding)
Configurable
null
means that the output encoding is not known.
Defaults to null
(unknown).
setOutputEncoding
in class Configurable
public boolean applyEqualsOperator(TemplateModel leftValue, TemplateModel rightValue) throws TemplateException
TemplateModel
-s according the rules of the FTL "==" operator.TemplateException
public boolean applyEqualsOperatorLenient(TemplateModel leftValue, TemplateModel rightValue) throws TemplateException
TemplateModel
-s according the rules of the FTL "==" operator, except that if the two types
are incompatible, they are treated as non-equal instead of throwing an exception. Comparing dates of
different types (date-only VS time-only VS date-time) will still throw an exception, however.TemplateException
public boolean applyLessThanOperator(TemplateModel leftValue, TemplateModel rightValue) throws TemplateException
TemplateModel
-s according the rules of the FTL "<" operator.TemplateException
public boolean applyLessThanOrEqualsOperator(TemplateModel leftValue, TemplateModel rightValue) throws TemplateException
TemplateModel
-s according the rules of the FTL "<" operator.TemplateException
public boolean applyGreaterThanOperator(TemplateModel leftValue, TemplateModel rightValue) throws TemplateException
TemplateModel
-s according the rules of the FTL ">" operator.TemplateException
public boolean applyWithGreaterThanOrEqualsOperator(TemplateModel leftValue, TemplateModel rightValue) throws TemplateException
TemplateModel
-s according the rules of the FTL ">=" operator.TemplateException
public void setOut(Writer out)
public Writer getOut()
public void setNumberFormat(String formatName)
Configurable
DecimalFormat
pattern (like "0.##"
), or one of the following special values:
"number"
: The number format returned by NumberFormat.getNumberInstance(Locale)
"currency"
: The number format returned by NumberFormat.getCurrencyInstance(Locale)
"percent"
: The number format returned by NumberFormat.getPercentInstance(Locale)
"computer"
: The number format used by FTL's c
built-in (like in someNumber?c
).Defaults to "number".
setNumberFormat
in class Configurable
public void setTimeFormat(String timeFormat)
Configurable
Date
-s to string-s that are time (no date part) values,
also the format that someString?time
will use to parse strings.
For the possible values see Configurable.setDateTimeFormat(String)
.
Defaults to ""
, which means "use the FreeMarker default", which is currently "medium"
.
setTimeFormat
in class Configurable
public void setDateFormat(String dateFormat)
Configurable
Date
-s to string-s that are date (no time part) values,
also the format that someString?date
will use to parse strings.
For the possible values see Configurable.setDateTimeFormat(String)
.
Defaults to ""
, which means "use the FreeMarker default", which is currently "code"
.
setDateFormat
in class Configurable
public void setDateTimeFormat(String dateTimeFormat)
Configurable
Date
-s to string-s that are date-time (timestamp) values,
also the format that someString?datetime
will use to parse strings.
The possible setting values are (the quotation marks aren't part of the value itself):
Patterns accepted by Java's SimpleDateFormat
, for example "dd.MM.yyyy HH:mm:ss"
(where
HH
means 24 hours format) or "MM/dd/yyyy hh:mm:ss a"
(where a
prints AM or PM, if
the current language is English).
"xs"
for XML Schema format, or "iso"
for ISO 8601:2004 format.
These formats allow various additional options, separated with space, like in
"iso m nz"
(or with _
, like in "iso_m_nz"
; this is useful in a case like
lastModified?string.iso_m_nz
). The options and their meanings are:
Accuracy options:
ms
= Milliseconds, always shown with all 3 digits, even if it's all 0-s.
Example: 13:45:05.800
s
= Seconds (fraction seconds are dropped even if non-0), like 13:45:05
m
= Minutes, like 13:45
. This isn't allowed for "xs".
h
= Hours, like 13
. This isn't allowed for "xs".
Neither = Up to millisecond accuracy, but trailing millisecond 0-s are removed, also the whole
milliseconds part if it would be 0 otherwise. Example: 13:45:05.8
Time zone offset visibility options:
fz
= "Force Zone", always show time zone offset (even for for
java.sql.Date
and java.sql.Time
values).
But, because ISO 8601 doesn't allow for dates (means date without time of the day) to
show the zone offset, this option will have no effect in the case of "iso"
with
dates.
nz
= "No Zone", never show time zone offset
Neither = always show time zone offset, except for java.sql.Date
and java.sql.Time
, and for "iso"
date values.
Time zone options:
u
= Use UTC instead of what the time_zone
setting suggests. However,
java.sql.Date
and java.sql.Time
aren't affected
by this (see Configurable.setSQLDateAndTimeTimeZone(TimeZone)
to understand why)
fu
= "Force UTC", that is, use UTC instead of what the time_zone
or the
sql_date_and_time_time_zone
setting suggests. This also effects
java.sql.Date
and java.sql.Time
values
Neither = Use the time zone suggested by the time_zone
or the
sql_date_and_time_time_zone
configuration setting (Configurable.setTimeZone(TimeZone)
and
Configurable.setSQLDateAndTimeTimeZone(TimeZone)
).
The options can be specified in any order.
Options from the same category are mutually exclusive, like using m
and s
together is an error.
The accuracy and time zone offset visibility options don't influence parsing, only formatting. For example, even if you use "iso m nz", "2012-01-01T15:30:05.125+01" will be parsed successfully and with milliseconds accuracy. The time zone options (like "u") influence what time zone is chosen only when parsing a string that doesn't contain time zone offset.
Parsing with "iso"
understands both extend format and basic format, like
20141225T235018
. It doesn't, however, support the parsing of all kind of ISO 8601 strings: if
there's a date part, it must use year, month and day of the month values (not week of the year), and the
day can't be omitted.
The output of "iso"
is deliberately so that it's also a good representation of the value with
XML Schema format, except for 0 and negative years, where it's impossible. Also note that the time zone
offset is omitted for date values in the "iso"
format, while it's preserved for the "xs"
format.
"short"
, "medium"
, "long"
, or "full"
, which that has locale-dependent
meaning defined by the Java platform (see in the documentation of DateFormat
).
For date-time values, you can specify the length of the date and time part independently, be separating
them with _
, like "short_medium"
. ("medium"
means
"medium_medium"
for date-time values.)
Defaults to ""
, which means "use the FreeMarker default", which is currently "code"
.
setDateTimeFormat
in class Configurable
public Configuration getConfiguration()
public NumberFormat getCNumberFormat()
NumberFormat
used for the c built-in.
This is always US English "0.################"
, without
grouping and without superfluous decimal separator.public TemplateModel getLocalVariable(String name) throws TemplateModelException
TemplateModelException
public TemplateModel getVariable(String name) throws TemplateModelException
TemplateModelException
public TemplateModel getGlobalVariable(String name) throws TemplateModelException
.globals.name
.
This will first look at variables that were assigned globally via:
<#global ...> and then at the data model exposed to the template.TemplateModelException
public void setGlobalVariable(String name, TemplateModel model)
<#global name=model>
.
This can be considered a convenient shorthand for:
getGlobalNamespace().put(name, model)public void setVariable(String name, TemplateModel model)
<#assign name=model>
.
This can be considered a convenient shorthand for:
getCurrentNamespace().put(name, model)public void setLocalVariable(String name, TemplateModel model)
<#local name=model>
.name
- the identifier of the variablemodel
- the value of the variable.IllegalStateException
- if the environment is not executing a
macro body.public Set getKnownVariableNames() throws TemplateModelException
Configuration
,
names of all global variables that were assigned during the template processing,
names of all variables in the current name-space, names of all local variables
and loop variables. If the passed root data model implements the
TemplateHashModelEx
interface, then all names it retrieves through a call to
TemplateHashModelEx.keys()
method are returned as well.
The method returns a new Set object on each call that is completely
disconnected from the Environment. That is, modifying the set will have
no effect on the Environment object.TemplateModelException
public void outputInstructionStack(PrintWriter pw)
TemplateException
s incorporate this information in their stack traces.public Environment.Namespace getNamespace(String name)
name
- the template path that you have used with the import
directive
or importLib(String, String)
call, in normalized form. That is, the path must be an absolute
path, and it must not contain "/../" or "/./". The leading "/" is optional.public Environment.Namespace getMainNamespace()
.main
hash.public Environment.Namespace getCurrentNamespace()
.namespace
hash.
Initially, the current name space is the main namespace, but when inside an #import
-ed template, it will
change to the namespace of that import. Note that #include
doesn't affect the namespace, so if you are
in an #import
-ed template and then from there do an #include
, the current namespace will remain
the namespace of the #import
.public Environment.Namespace getGlobalNamespace()
<#global ...>
).public TemplateHashModel getDataModel()
public TemplateHashModel getGlobalVariables()
.globals
hash.
That is, you see the variables created with
<#global ...>
, and the variables of the data-model.
To create new global variables, use setGlobalVariable
.public TemplateNodeModel getCurrentVisitorNode()
public void setCurrentVisitorNode(TemplateNodeModel node)
public void include(String name, String encoding, boolean parse) throws IOException, TemplateException
include
directive, except that name
must be tempate
root relative.
It's the same as include(getTemplateForInclusion(name, encoding, parse))
.
But, you may want to separately call these two methods, so you can determine the source of
exceptions more precisely, and thus achieve more intelligent error handling.
public Template getTemplateForInclusion(String name, String encoding, boolean parse) throws IOException
getTemplateForInclusion(String, String, boolean, boolean)
with false
ignoreMissign
argument.IOException
public Template getTemplateForInclusion(String name, String encoding, boolean parseAsFTL, boolean ignoreMissing) throws IOException
include(Template includedTemplate)
. The advantage
over simply using config.getTemplate(...)
is that it chooses the default encoding exactly as the
include
directive does, although that encoding selection mechanism is a historical baggage and
considered to be harmful.name
- the name of the template, relatively to the template root directory (not the to the directory of the
currently executing template file). (Note that you can use
TemplateCache.getFullTemplatePath(freemarker.core.Environment, java.lang.String, java.lang.String)
to convert paths to template root relative
paths.) For more details see the identical parameter of
Configuration.getTemplate(String, Locale, String, boolean, boolean)
encoding
- the charset of the obtained template. If null
, the encoding of the top template that is
currently being processed in this Environment
is used, which can lead to odd situations, so
using null
is not recommended. In most applications, the value of
Configuration.getEncoding(Locale)
(or Configuration.getDefaultEncoding()
) should be
used here.parseAsFTL
- See identical parameter of Configuration.getTemplate(String, Locale, String, boolean, boolean)
ignoreMissing
- See identical parameter of Configuration.getTemplate(String, Locale, String, boolean, boolean)
Configuration.getTemplate(String, Locale, String, boolean, boolean)
IOException
- Same as exceptions thrown by
Configuration.getTemplate(String, Locale, String, boolean, boolean)
public void include(Template includedTemplate) throws TemplateException, IOException
Environment
, including its
output in the Environment
's Writer.includedTemplate
- the template to process. Note that it does not need
to be a template returned by
getTemplateForInclusion(String name, String encoding, boolean parse)
.TemplateException
IOException
public Environment.Namespace importLib(String name, String namespace) throws IOException, TemplateException
import
directive, except that name
must be tempate
root relative.
It's the same as importLib(getTemplateForImporting(name), namespace)
.
But, you may want to separately call these two methods, so you can determine the source of
exceptions more precisely, and thus achieve more intelligent error handling.
public Template getTemplateForImporting(String name) throws IOException
importLib(Template importedTemplate, String namespace)
. The advantage
over simply using config.getTemplate(...)
is that it chooses the encoding
as the import
directive does.name
- the name of the template, relatively to the template root directory
(not the to the directory of the currently executing template file!).
(Note that you can use TemplateCache.getFullTemplatePath(freemarker.core.Environment, java.lang.String, java.lang.String)
to convert paths to template root relative paths.)IOException
public Environment.Namespace importLib(Template loadedTemplate, String namespace) throws IOException, TemplateException
import
directive.loadedTemplate
- the template to import. Note that it does not need
to be a template returned by getTemplateForImporting(String name)
.IOException
TemplateException
public String toFullTemplateName(String baseName, String targetName) throws MalformedTemplateNameException
#include
or #import
), assuming a base
name. This gives a full (that is, absolute), even if non-normalized template name, that could be used for
Configuration.getTemplate(String)
. This is mostly used when a template refers to another template.baseName
- The name to which relative targetName
-s are relative to. Maybe null
, which usually
means that the base is the root "directory". Assuming TemplateNameFormat.DEFAULT_2_3_0
or
TemplateNameFormat.DEFAULT_2_4_0
, the rules are as follows. If you want to specify a base
directory here, it must end with "/"
. If it doesn't end with "/"
, it's parent
directory will be used as the base path. Might starts with a scheme part (like "foo://"
, or
with TemplateNameFormat.DEFAULT_2_4_0
even just "foo:"
).targetName
- The name of the template, which is either a relative or absolute name. Assuming
TemplateNameFormat.DEFAULT_2_3_0
or TemplateNameFormat.DEFAULT_2_4_0
, the rules are as
follows. If it starts with "/"
or contains a scheme part separator ("://"
, also, with
TemplateNameFormat.DEFAULT_2_4_0
a ":"
with no "/"
anywhere before it) then
it's an absolute name, otherwise it's a relative path. Relative paths are interpreted relatively to
the baseName
. Absolute names are simply returned as is, ignoring the baseName
, except,
when the baseName
has scheme part while the targetName
doesn't have, then the schema
of the baseName
is prepended to the targetName
.MalformedTemplateNameException
public String getNamespaceForPrefix(String prefix)
public String getDefaultNS()
public Object __getitem__(String key) throws TemplateModelException
TemplateModelException
public void __setitem__(String key, Object o) throws TemplateException
TemplateException