Class Environment
- java.lang.Object
-
- freemarker.core.Configurable
-
- freemarker.core.Environment
-
public final class Environment extends Configurable
Object that represents the runtime environment during template processing. For every invocation of a Template.process() method, a new instance of this object is created, and then discarded when process() returns. This object stores the set of temporary variables created by the template, the value of settings set by the template, the reference to the data model root, etc. Everything that is needed to fulfill the template processing job.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)
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description class
Environment.Namespace
-
Nested classes/interfaces inherited from class freemarker.core.Configurable
Configurable.SettingValueAssignmentException, Configurable.UnknownSettingException
-
-
Field Summary
-
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 Environment(Template template, TemplateHashModel rootDataModel, Writer out)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method 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 twoTemplateModel
-s according the rules of the FTL "==" operator.boolean
applyEqualsOperatorLenient(TemplateModel leftValue, TemplateModel rightValue)
Compares twoTemplateModel
-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 twoTemplateModel
-s according the rules of the FTL ">" operator.boolean
applyLessThanOperator(TemplateModel leftValue, TemplateModel rightValue)
Compares twoTemplateModel
-s according the rules of the FTL "<" operator.boolean
applyLessThanOrEqualsOperator(TemplateModel leftValue, TemplateModel rightValue)
Compares twoTemplateModel
-s according the rules of the FTL "<" operator.boolean
applyWithGreaterThanOrEqualsOperator(TemplateModel leftValue, TemplateModel rightValue)
Compares twoTemplateModel
-s according the rules of the FTL ">=" operator.NumberFormat
getCNumberFormat()
Returns theNumberFormat
used for the c built-in.Configuration
getConfiguration()
DirectiveCallPlace
getCurrentDirectiveCallPlace()
Gets the currently executing custom directive's call place information, ornull
if there's no executing custom directive.static Environment
getCurrentEnvironment()
Retrieves the environment object associated with the current thread, ornull
if there's no template processing going on in this thread.Environment.Namespace
getCurrentNamespace()
Returns the current namespace.Template
getCurrentTemplate()
Returns theTemplate
that we are "lexically" inside at the moment.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 topmostTemplate
, with other words, the one for which thisEnvironment
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.UsegetMainTemplate()
instead (orgetCurrentNamespace()
and thenEnvironment.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 withimportLib(Template importedTemplate, String namespace)
.Template
getTemplateForInclusion(String name, String encoding, boolean parse)
Same asgetTemplateForInclusion(String, String, boolean, boolean)
withfalse
ignoreMissign
argument.Template
getTemplateForInclusion(String name, String encoding, boolean parseAsFTL, boolean ignoreMissing)
Gets a template for inclusion; used for implementinginclude(Template includedTemplate)
.TemplateModel
getVariable(String name)
Returns the variable that is visible in this context, ornull
if the variable is not found.Environment.Namespace
importLib(Template loadedTemplate, String namespace)
Emulatesimport
directive.Environment.Namespace
importLib(String name, String namespace)
Emulatesimport
directive, except thatname
must be tempate root relative.void
include(Template includedTemplate)
Processes a Template in the context of thisEnvironment
, including its output in theEnvironment
's Writer.void
include(String name, String encoding, boolean parse)
Emulatesinclude
directive, except thatname
must be tempate root relative.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 convertDate
-s to string-s that are date (no time part) values, also the format thatsomeString?date
will use to parse strings.void
setDateTimeFormat(String dateTimeFormat)
Sets the format used to convertDate
-s to string-s that are date-time (timestamp) values, also the format thatsomeString?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 withjava.sql.Date
andjava.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 convertDate
-s to string-s that are time (no date part) values, also the format thatsomeString?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)
-
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, setLogTemplateExceptions, setNewBuiltinClassResolver, setObjectWrapper, setSetting, setSettings, setSettings, setShowErrorTips, setStrictBeanModels, settingValueAssignmentException, unknownSettingException
-
-
-
-
Constructor Detail
-
Environment
public Environment(Template template, TemplateHashModel rootDataModel, Writer out)
-
-
Method Detail
-
getCurrentEnvironment
public static Environment getCurrentEnvironment()
Retrieves the environment object associated with the current thread, ornull
if there's no template processing going on in this thread. Data model implementations that need access to the environment can call this method to obtain the environment object that represents the template processing that is currently running on the current thread.
-
getTemplate
public Template getTemplate()
Deprecated.UsegetMainTemplate()
instead (orgetCurrentNamespace()
and thenEnvironment.Namespace.getTemplate()
); the value returned by this method is often not what you expect when it comes to macro/function invocations.Despite its name it just returnsConfigurable.getParent()
. IfConfiguration.getIncompatibleImprovements()
is at least 2.3.22, then that will be the same asgetMainTemplate()
. Otherwise the returned value follows theEnvironment
parent switchings that occur at#include
/#import
and#nested
directive calls, that is, it's not very meaningful outside FreeMarker internals.
-
getMainTemplate
public Template getMainTemplate()
Returns the topmostTemplate
, with other words, the one for which thisEnvironment
was created. That template will never change, like#include
or macro calls don't change it.- Since:
- 2.3.22
- See Also:
getCurrentNamespace()
-
getCurrentTemplate
public Template getCurrentTemplate()
Returns theTemplate
that we are "lexically" inside at the moment. This template will change when entering an#include
or calling a macro or function in another template, or returning to yet another template with#nested
. As such, it's useful inTemplateDirectiveModel
to find out if from where the directive was called from.- Since:
- 2.3.23
- See Also:
getMainTemplate()
,getCurrentNamespace()
-
getCurrentDirectiveCallPlace
public DirectiveCallPlace getCurrentDirectiveCallPlace()
Gets the currently executing custom directive's call place information, ornull
if there's no executing custom directive. This currently only works for calls made from templates with the<@...>
syntax. This should only be called from theTemplateDirectiveModel
that was invoked with<@...>
, otherwise its return value is not defined by this API (it's usuallynull
).- Since:
- 2.3.22
-
process
public void process() throws TemplateException, IOException
Processes the template to which this environment belongs to.- Throws:
TemplateException
IOException
-
visit
public void visit(freemarker.core.TemplateElement element, TemplateDirectiveModel directiveModel, Map args, List bodyParameterNames) throws TemplateException, IOException
- Throws:
TemplateException
IOException
-
isInAttemptBlock
public boolean isInAttemptBlock()
Tells if we are inside an #attempt block (but before #recover). This can be useful forTemplateExceptionHandler
-s, as then they may don't want to print the error to the output, as #attempt will roll it back anyway.- Since:
- 2.3.20
-
setTemplateExceptionHandler
public void setTemplateExceptionHandler(TemplateExceptionHandler templateExceptionHandler)
Description copied from class:Configurable
Sets the exception handler used to handle exceptions occurring inside templates. The default isTemplateExceptionHandler.DEBUG_HANDLER
. The recommended values are:- In production systems:
TemplateExceptionHandler.RETHROW_HANDLER
- During development of HTML templates:
TemplateExceptionHandler.HTML_DEBUG_HANDLER
- During development of non-HTML templates:
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 fromTemplate.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.- Overrides:
setTemplateExceptionHandler
in classConfigurable
- In production systems:
-
setLocale
public void setLocale(Locale locale)
Description copied from class:Configurable
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.- Overrides:
setLocale
in classConfigurable
- See Also:
Configuration.getTemplate(String, Locale)
-
setTimeZone
public void setTimeZone(TimeZone timeZone)
Description copied from class:Configurable
Sets the time zone to use when formatting date/time values. Defaults to the system time zone (TimeZone.getDefault()
), regardless of the "locale" FreeMarker setting, so in a server application you probably want to set it explicitly in theEnvironment
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)
!- Overrides:
setTimeZone
in classConfigurable
- See Also:
Configurable.setSQLDateAndTimeTimeZone(TimeZone)
-
setSQLDateAndTimeTimeZone
public void setSQLDateAndTimeTimeZone(TimeZone timeZone)
Description copied from class:Configurable
Sets the time zone used when dealing withjava.sql.Date
andjava.sql.Time
values. It defaults tonull
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 thejava.sql.Date
andjava.sql.Time
values. If this setting isnull
, FreeMarker will use the value of (Configurable.getTimeZone()
) forjava.sql.Date
andjava.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 plainjava.util.Date
values).To decide what value you need, a few things has to be understood:
- Date-only and time-only values in SQL-oriented databases are usually store calendar and clock field values directly (year, month, day, or hour, minute, seconds (with decimals)), as opposed to a set of points on the physical time line. Thus, unlike SQL timestamps, these values usually aren't meant to be shown differently depending on the time zone of the audience.
- When a JDBC query has to return a date-only or time-only value, it has to convert it to a point on the
physical time line, because that's what
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.) - The value of the
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 callssetTimeZone(TimeZone)
with that time zone. Thus, the visitor will seejava.sql.Timestamp
and plainjava.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. Whensql_date_and_time_time_zone
isnull
,time_zone
is used for rendering all kind of date/time/dateTime values, includingjava.sql.Date
andjava.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". - You may wonder why this setting isn't simply "SQL time zone", since the time zone related behavior of JDBC
applies to
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 byDate
. In that case the time stamp can be safely rendered in different time zones, and thus it needs no special treatment.
- Overrides:
setSQLDateAndTimeTimeZone
in classConfigurable
- Parameters:
timeZone
- Maybenull
, in which casejava.sql.Date
andjava.sql.Time
values will be formatted in the time zone returned byConfigurable.getTimeZone()
. (Note that sincenull
is an allowed value for this setting, it will not causeConfigurable.getSQLDateAndTimeTimeZone()
to fall back to the parent configuration.)- See Also:
Configurable.setTimeZone(TimeZone)
-
setURLEscapingCharset
public void setURLEscapingCharset(String urlEscapingCharset)
Description copied from class:Configurable
Sets the URL escaping charset. If not set (null
), the output encoding (Configurable.setOutputEncoding(String)
) will be used for URL escaping. Defaults tonull
.- Overrides:
setURLEscapingCharset
in classConfigurable
-
setOutputEncoding
public void setOutputEncoding(String outputEncoding)
Description copied from class:Configurable
Informs FreeMarker about the charset used for the output. As FreeMarker outputs character stream (not byte stream), it's not aware of the output charset unless the software that encloses it tells it with this setting. Some templates may use FreeMarker features that require this information. Setting this tonull
means that the output encoding is not known.Defaults to
null
(unknown).- Overrides:
setOutputEncoding
in classConfigurable
-
applyEqualsOperator
public boolean applyEqualsOperator(TemplateModel leftValue, TemplateModel rightValue) throws TemplateException
Compares twoTemplateModel
-s according the rules of the FTL "==" operator.- Throws:
TemplateException
- Since:
- 2.3.20
-
applyEqualsOperatorLenient
public boolean applyEqualsOperatorLenient(TemplateModel leftValue, TemplateModel rightValue) throws TemplateException
Compares twoTemplateModel
-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.- Throws:
TemplateException
- Since:
- 2.3.20
-
applyLessThanOperator
public boolean applyLessThanOperator(TemplateModel leftValue, TemplateModel rightValue) throws TemplateException
Compares twoTemplateModel
-s according the rules of the FTL "<" operator.- Throws:
TemplateException
- Since:
- 2.3.20
-
applyLessThanOrEqualsOperator
public boolean applyLessThanOrEqualsOperator(TemplateModel leftValue, TemplateModel rightValue) throws TemplateException
Compares twoTemplateModel
-s according the rules of the FTL "<" operator.- Throws:
TemplateException
- Since:
- 2.3.20
-
applyGreaterThanOperator
public boolean applyGreaterThanOperator(TemplateModel leftValue, TemplateModel rightValue) throws TemplateException
Compares twoTemplateModel
-s according the rules of the FTL ">" operator.- Throws:
TemplateException
- Since:
- 2.3.20
-
applyWithGreaterThanOrEqualsOperator
public boolean applyWithGreaterThanOrEqualsOperator(TemplateModel leftValue, TemplateModel rightValue) throws TemplateException
Compares twoTemplateModel
-s according the rules of the FTL ">=" operator.- Throws:
TemplateException
- Since:
- 2.3.20
-
setOut
public void setOut(Writer out)
-
getOut
public Writer getOut()
-
setNumberFormat
public void setNumberFormat(String formatName)
Description copied from class:Configurable
Sets the default number format used to convert numbers to strings. Currently, this is either aDecimalFormat
pattern (like"0.##"
), or one of the following special values:"number"
: The number format returned byNumberFormat.getNumberInstance(Locale)
"currency"
: The number format returned byNumberFormat.getCurrencyInstance(Locale)
"percent"
: The number format returned byNumberFormat.getPercentInstance(Locale)
"computer"
: The number format used by FTL'sc
built-in (like insomeNumber?c
).
Defaults to "number".
- Overrides:
setNumberFormat
in classConfigurable
-
setTimeFormat
public void setTimeFormat(String timeFormat)
Description copied from class:Configurable
Sets the format used to convertDate
-s to string-s that are time (no date part) values, also the format thatsomeString?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"
.- Overrides:
setTimeFormat
in classConfigurable
-
setDateFormat
public void setDateFormat(String dateFormat)
Description copied from class:Configurable
Sets the format used to convertDate
-s to string-s that are date (no time part) values, also the format thatsomeString?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"
.- Overrides:
setDateFormat
in classConfigurable
-
setDateTimeFormat
public void setDateTimeFormat(String dateTimeFormat)
Description copied from class:Configurable
Sets the format used to convertDate
-s to string-s that are date-time (timestamp) values, also the format thatsomeString?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"
(whereHH
means 24 hours format) or"MM/dd/yyyy hh:mm:ss a"
(wherea
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 likelastModified?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), like13:45:05
m
= Minutes, like13:45
. This isn't allowed for "xs".
h
= Hours, like13
. 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 forjava.sql.Date
andjava.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 forjava.sql.Date
andjava.sql.Time
, and for"iso"
date values.Time zone options:
u
= Use UTC instead of what thetime_zone
setting suggests. However,java.sql.Date
andjava.sql.Time
aren't affected by this (seeConfigurable.setSQLDateAndTimeTimeZone(TimeZone)
to understand why)
fu
= "Force UTC", that is, use UTC instead of what thetime_zone
or thesql_date_and_time_time_zone
setting suggests. This also effectsjava.sql.Date
andjava.sql.Time
values
Neither = Use the time zone suggested by thetime_zone
or thesql_date_and_time_time_zone
configuration setting (Configurable.setTimeZone(TimeZone)
andConfigurable.setSQLDateAndTimeTimeZone(TimeZone)
).
The options can be specified in any order.
Options from the same category are mutually exclusive, like using
m
ands
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, like20141225T235018
. 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 ofDateFormat
). 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"
.- Overrides:
setDateTimeFormat
in classConfigurable
-
getConfiguration
public Configuration getConfiguration()
-
getCNumberFormat
public NumberFormat getCNumberFormat()
Returns theNumberFormat
used for the c built-in. This is always US English"0.################"
, without grouping and without superfluous decimal separator.
-
getLocalVariable
public TemplateModel getLocalVariable(String name) throws TemplateModelException
Returns the loop or macro local variable corresponding to this variable name. Possibly null. (Note that the misnomer is kept for backward compatibility: loop variables are not local variables according to our terminology.)- Throws:
TemplateModelException
-
getVariable
public TemplateModel getVariable(String name) throws TemplateModelException
Returns the variable that is visible in this context, ornull
if the variable is not found. This is the correspondent to an FTL top-level variable reading expression. That is, it tries to find the the variable in this order:- An loop variable (if we're in a loop or user defined directive body) such as foo_has_next
- A local variable (if we're in a macro)
- A variable defined in the current namespace (say, via <#assign ...>)
- A variable defined globally (say, via <#global ....>)
- Variable in the data model:
- A variable in the root hash that was exposed to this rendering environment in the Template.process(...) call
- A shared variable set in the configuration via a call to Configuration.setSharedVariable(...)
- Throws:
TemplateModelException
-
getGlobalVariable
public TemplateModel getGlobalVariable(String name) throws TemplateModelException
Returns the globally visible variable of the given name (or null). This is correspondent to FTL.globals.name
. This will first look at variables that were assigned globally via: <#global ...> and then at the data model exposed to the template.- Throws:
TemplateModelException
-
setGlobalVariable
public void setGlobalVariable(String name, TemplateModel model)
Sets a variable that is visible globally. This is correspondent to FTL<#global name=model>
. This can be considered a convenient shorthand for: getGlobalNamespace().put(name, model)
-
setVariable
public void setVariable(String name, TemplateModel model)
Sets a variable in the current namespace. This is correspondent to FTL<#assign name=model>
. This can be considered a convenient shorthand for: getCurrentNamespace().put(name, model)
-
setLocalVariable
public void setLocalVariable(String name, TemplateModel model)
Sets a local variable (one effective only during a macro invocation). This is correspondent to FTL<#local name=model>
.- Parameters:
name
- the identifier of the variablemodel
- the value of the variable.- Throws:
IllegalStateException
- if the environment is not executing a macro body.
-
getKnownVariableNames
public Set getKnownVariableNames() throws TemplateModelException
Returns a set of variable names that are known at the time of call. This includes names of all shared variables in theConfiguration
, 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 theTemplateHashModelEx
interface, then all names it retrieves through a call toTemplateHashModelEx.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.- Throws:
TemplateModelException
-
outputInstructionStack
public void outputInstructionStack(PrintWriter pw)
Prints the current FTL stack trace. Useful for debugging.TemplateException
s incorporate this information in their stack traces.
-
getNamespace
public Environment.Namespace getNamespace(String name)
Returns the name-space for the name if exists, or null.- Parameters:
name
- the template path that you have used with theimport
directive orimportLib(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.
-
getMainNamespace
public Environment.Namespace getMainNamespace()
Returns the main namespace. This corresponds to the FTL.main
hash.
-
getCurrentNamespace
public Environment.Namespace getCurrentNamespace()
Returns the current namespace. This corresponds to the FTL.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
.
-
getGlobalNamespace
public Environment.Namespace getGlobalNamespace()
Returns the name-space that contains the globally visible non-data-model variables (usually created with<#global ...>
).
-
getDataModel
public TemplateHashModel getDataModel()
Returns the data-model (also known as the template context in some other template engines).
-
getGlobalVariables
public TemplateHashModel getGlobalVariables()
Returns the read-only hash of globally visible variables. This is the correspondent of FTL.globals
hash. That is, you see the variables created with<#global ...>
, and the variables of the data-model. To create new global variables, usesetGlobalVariable
.
-
getCurrentVisitorNode
public TemplateNodeModel getCurrentVisitorNode()
-
setCurrentVisitorNode
public void setCurrentVisitorNode(TemplateNodeModel node)
sets TemplateNodeModel as the current visitor node. .current_node
-
include
public void include(String name, String encoding, boolean parse) throws IOException, TemplateException
Emulatesinclude
directive, except thatname
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.
-
getTemplateForInclusion
public Template getTemplateForInclusion(String name, String encoding, boolean parse) throws IOException
Same asgetTemplateForInclusion(String, String, boolean, boolean)
withfalse
ignoreMissign
argument.- Throws:
IOException
-
getTemplateForInclusion
public Template getTemplateForInclusion(String name, String encoding, boolean parseAsFTL, boolean ignoreMissing) throws IOException
Gets a template for inclusion; used for implementinginclude(Template includedTemplate)
. The advantage over simply usingconfig.getTemplate(...)
is that it chooses the default encoding exactly as theinclude
directive does, although that encoding selection mechanism is a historical baggage and considered to be harmful.- Parameters:
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 useTemplateCache.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 ofConfiguration.getTemplate(String, Locale, String, boolean, boolean)
encoding
- the charset of the obtained template. Ifnull
, the encoding of the top template that is currently being processed in thisEnvironment
is used, which can lead to odd situations, so usingnull
is not recommended. In most applications, the value ofConfiguration.getEncoding(Locale)
(orConfiguration.getDefaultEncoding()
) should be used here.parseAsFTL
- See identical parameter ofConfiguration.getTemplate(String, Locale, String, boolean, boolean)
ignoreMissing
- See identical parameter ofConfiguration.getTemplate(String, Locale, String, boolean, boolean)
- Returns:
- Same as
Configuration.getTemplate(String, Locale, String, boolean, boolean)
- Throws:
IOException
- Same as exceptions thrown byConfiguration.getTemplate(String, Locale, String, boolean, boolean)
- Since:
- 2.3.21
-
include
public void include(Template includedTemplate) throws TemplateException, IOException
Processes a Template in the context of thisEnvironment
, including its output in theEnvironment
's Writer.- Parameters:
includedTemplate
- the template to process. Note that it does not need to be a template returned bygetTemplateForInclusion(String name, String encoding, boolean parse)
.- Throws:
TemplateException
IOException
-
importLib
public Environment.Namespace importLib(String name, String namespace) throws IOException, TemplateException
Emulatesimport
directive, except thatname
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.
-
getTemplateForImporting
public Template getTemplateForImporting(String name) throws IOException
Gets a template for importing; used withimportLib(Template importedTemplate, String namespace)
. The advantage over simply usingconfig.getTemplate(...)
is that it chooses the encoding as theimport
directive does.- Parameters:
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 useTemplateCache.getFullTemplatePath(freemarker.core.Environment, java.lang.String, java.lang.String)
to convert paths to template root relative paths.)- Throws:
IOException
-
importLib
public Environment.Namespace importLib(Template loadedTemplate, String namespace) throws IOException, TemplateException
Emulatesimport
directive.- Parameters:
loadedTemplate
- the template to import. Note that it does not need to be a template returned bygetTemplateForImporting(String name)
.- Throws:
IOException
TemplateException
-
toFullTemplateName
public String toFullTemplateName(String baseName, String targetName) throws MalformedTemplateNameException
Resolves a reference to a template (like the one used in#include
or#import
), assuming a base name. This gives a full (that is, absolute), even if non-normalized template name, that could be used forConfiguration.getTemplate(String)
. This is mostly used when a template refers to another template.- Parameters:
baseName
- The name to which relativetargetName
-s are relative to. Maybenull
, which usually means that the base is the root "directory". AssumingTemplateNameFormat.DEFAULT_2_3_0
orTemplateNameFormat.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 withTemplateNameFormat.DEFAULT_2_4_0
even just"foo:"
).targetName
- The name of the template, which is either a relative or absolute name. AssumingTemplateNameFormat.DEFAULT_2_3_0
orTemplateNameFormat.DEFAULT_2_4_0
, the rules are as follows. If it starts with"/"
or contains a scheme part separator ("://"
, also, withTemplateNameFormat.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 thebaseName
. Absolute names are simply returned as is, ignoring thebaseName
, except, when thebaseName
has scheme part while thetargetName
doesn't have, then the schema of thebaseName
is prepended to thetargetName
.- Throws:
MalformedTemplateNameException
- Since:
- 2.3.22
-
getNamespaceForPrefix
public String getNamespaceForPrefix(String prefix)
- Returns:
- the namespace URI registered for this prefix, or null. This is based on the mappings registered in the current namespace.
-
getDefaultNS
public String getDefaultNS()
- Returns:
- the default node namespace for the current FTL namespace
-
__getitem__
public Object __getitem__(String key) throws TemplateModelException
A hook that Jython uses.- Throws:
TemplateModelException
-
__setitem__
public void __setitem__(String key, Object o) throws TemplateException
A hook that Jython uses.- Throws:
TemplateException
-
-