Special variables are variables defined by the FreeMarker engine
itself. To access them, you use the
.variable_name
syntax. For
example, you can't write simply version
; you have to
write .version
.
As of FreeMarker 2.3.23, you can use camel case instead of snake
case for special variable names, like dataModel
instead of data_model
. But know that then within
the same template, FreeMarker will enforce the usage of camel case for
all identifiers that are part of the template language (user defined
names are not affected).
The supported special variables are:
-
auto_esc
(since 2.3.24): Boolean value that tells if auto-escaping (based on output format) is on or off at the place where this variable is referred (resolved statically). This is not affected by the deprecatedescape
directive. This only deals with automatic escaping based on the output format mechanism. -
current_template_name
: The name of the template where we are now (available since FreeMarker 2.3.23). This can be missing (null
) if the template was created on-the-fly in Java (vianew Template(null, ...)
), rather than loaded from a backing store by name (viacfg.getTemplate(name, ...)
). Migration notice: If you replace the deprecatedtemplate_name
with this, note that the later is a 0-length string instead of missing (null
) if the template has no name, so you might want to writecurrent_template_name!''
in legacy templates. -
data_model
: A hash that you can use to access the data-model directly. That is, variables you did withglobal
directive are not visible here. -
error
(available since FreeMarker 2.3.1): This variable accessible in the body of therecover
directive, where it stores the error message of the error we recover from. -
globals
: A hash that you can use to access the globally accessible variables: the data-model and the variables created withglobal
directive. Note that variables created withassign
ormacro
are not globals, thus they never hide the variables when you useglobals
. -
incompatible_improvements
(since FreeMarker 2.3.24): Theincompatible_improvements
setting of the current FreeMarker configuration, as a string. -
lang
: Returns the language part of the current value of the locale setting. For example if.locale
isen_US
, then.lang
isen
. -
locale
: Returns the current value of the locale setting. This is a string, for exampleen_US
. For more information about locale strings see thesetting
directive. -
locale_object
(available since FreeMarker 2.3.21): Returns the current value of the locale setting as ajava.util.Locale
object, rather than as a string. This meant to be used instead of.locale
when you want to pass it as ajava.util.Locale
object to a Java method. (TheLocale
object will be wrapped according theobject_wrapper
setting value. Whether you can actually pass this value to a Java method as aLocale
object depends on the object wrapper, but an object wrapper that let you call Java methods directly is very unlikely to not support that.) -
locals
: A hash that you can use to access the local variables (the variables created with thelocal
directive, and the parameters of macro). -
main
: A hash that you can use to access the main namespace. Note that global variables like the variables of data-model are not visible through this hash. -
main_template_name
: The name of the top level template (available since FreeMarker 2.3.23). (In Java, this is the template for whichTemplate.process
was called.) This can be missing (null
) if the template was created on-the-fly in Java (vianew Template(null, ...)
), rather than loaded from a backing store by name (viacfg.getTemplate(name, ...)
). Migration notice: If you replace the deprecatedtemplate_name
with this, note that the later is a 0-length string instead of missing (null
) if the template has no name, so you might want to writemain_template_name!''
in legacy templates. -
namespace
: A hash that you can use to access the current namespace. Note that global variables like the variables of data-model are not visible through this hash. -
node
(aliascurrent_node
for historical reasons): The node you are currently processing with the visitor pattern (i.e. with thevisit
,recurse
, ...etc. directives). Also, it initially stores the root node when you use the FreeMarker XML Ant task. -
now
: Returns the current date-time. Usage examples: "Page generated: ${.now}
", "Today is ${.now?date}
", "The current time is ${.now?time}
". -
Returns the name of the current output format.
This value is never missing/null. It's maybe the string
"undefined"
, which is just the name of the default output format. -
output_encoding
(available since FreeMarker 2.3.1): Returns the name of the current output charset. This special variable is not existent if the framework that encapsulates FreeMarker doesn't specify the output charset for FreeMarker. (Programmers can read more about charset issues here...) -
pass
: This is a macro that does nothing. It has no parameters. Mostly used as no-op node handler in XML processing. -
template_name
: Don't use it, because its behavior is strange when macros are used; usecurrent_template_name
ormain_template_name
instead (see migration notices there). Gives the name of the main template, or if we are running an included or imported template, the name of that template. When calling macros, it becomes rather confusing: the macro call won't change the value of this special variable, but whennested
is called, it changes it to the name of the template that belongs to the current namespace. (Available since FreeMarker 2.3.14.) -
url_escaping_charset
(available since FreeMarker 2.3.1): If exists, it stores the name of the charset that should be used for URL escaping. If this variable doesn't exist that means that nobody has specified what charset should be used for URL encoding yet. In this case theurl
built-in uses the charset specified by theoutput_encoding
special variable for URL encoding; custom mechanism may follow the same logic. (Programmers can read more about charset issues here...) -
output_format
(since 2.3.24): The name of output format at the place where this variable is referred (resolved statically), such as"HTML"
,"XML"
,"RTF"
,"plainText"
,"undefined"
, etc. (The available names can be extended by the programmers, by theregistered_custom_output_formats
setting.) -
vars
: Expression.vars.foo
returns the same variable as expressionfoo
. It's useful if for some reasons you have to use square bracket syntax, since that works only for hash sub variables, so you need an artificial parent hash. For example, to read a top-level variable that has a strange name that would confuse FreeMarker, you can write.vars["A strange name!"]
. Or, to access a top-level variable with dynamic name given with variablevarName
you can write.vars[varName]
. Note that the hash returned by.vars
does not support?keys
and?values
. -
version
: Returns the FreeMarker version number as string, for example2.2.8
. This can be used to check which FreeMarker version does your application use, but note that this special variable does not exist prior to the 2.3.0 or 2.2.8 versions. The version number of non-final releases contains dash and further info after the numbers, like in 2.3.21-nightly_20140726T151800Z.