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)
__setitem__
public void __setitem__(String key,
Object o)
throws TemplateException
A hook that Jython uses.
getCurrentEnvironment
public static Environment getCurrentEnvironment()
Retrieves the environment object associated with the current
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.
getCurrentNamespace
public Environment.Namespace getCurrentNamespace()
Returns the main name-space.
This is correspondent of FTL .namespace
hash.
getDataModel
public TemplateHashModel getDataModel()
Returns the data model hash.
This is correspondent of FTL .datamodel
hash.
That is, it contains both the variables of the root hash passed to the
Template.process(...)
, and the shared variables in the
Configuration
.
getDefaultNS
public String getDefaultNS()
- the default node namespace for the current FTL namespace
getGlobalNamespace
public Environment.Namespace getGlobalNamespace()
Returns a fictitious name-space that contains the globally visible variables
that were created in the template, but not the variables of the data-model.
There is no such thing in FTL; this strange method was added because of the
JSP taglib support, since this imaginary name-space contains the page-scope
attributes.
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.
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, use
setGlobalVariable
.
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 the
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.
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.)
getMainNamespace
public Environment.Namespace getMainNamespace()
Returns the main name-space.
This is correspondent of FTL .main
hash.
getNamespace
public Environment.Namespace getNamespace(String name)
Returns the name-space for the name if exists, or null.
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.
getNamespaceForPrefix
public String getNamespaceForPrefix(String prefix)
- the namespace URI registered for this prefix, or null.
This is based on the mappings registered in the current namespace.
getOut
public Writer getOut()
getPrefixForNamespace
public String getPrefixForNamespace(String nsURI)
getTemplate
public Template getTemplate()
Retrieves the currently processed template.
getTemplateForImporting
public Template getTemplateForImporting(String name)
throws IOException
Gets a template for importing; used with
importLib(Template importedTemplate, String namespace)
. The advantage
over simply using config.getTemplate(...)
is that it chooses the encoding
as the import
directive does.
getTemplateForInclusion
public Template getTemplateForInclusion(String name,
String encoding,
boolean parse)
throws IOException
Gets a template for inclusion; used with include(Template includedTemplate)
.
The advantage over simply using config.getTemplate(...)
is that it chooses
the default encoding as the include
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(Environment,String,String)
to convert paths to template root relative paths.)encoding
- the encoding of the obtained template. If null,
the encoding of the Template that is currently being processed in this
Environment is used.parse
- whether to process a parsed template or just include the
unparsed template source.
getVariable
public TemplateModel getVariable(String name)
throws TemplateModelException
Returns the variable that is visible in this context.
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(...)
importLib
public Environment.Namespace importLib(String name,
String namespace)
throws IOException,
TemplateException
Emulates
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.
getTemplateForImporting(String name)
, importLib(Template includedTemplate, String namespace)
importLib
public Environment.Namespace importLib(Template loadedTemplate,
String namespace)
throws IOException,
TemplateException
Emulates import
directive.
loadedTemplate
- the template to import. Note that it does not need
to be a template returned by getTemplateForImporting(String name)
.
include
public void include(String name,
String encoding,
boolean parse)
throws IOException,
TemplateException
Emulates
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.
getTemplateForInclusion(String name, String encoding, boolean parse)
, include(Template includedTemplate)
include
public void include(Template includedTemplate)
throws TemplateException,
IOException
Processes a Template in the context of this 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)
.
outputInstructionStack
public void outputInstructionStack(PrintWriter pw)
Outputs the instruction stack. Useful for debugging.
TemplateException
s incorporate this information in their stack
traces.
process
public void process()
throws TemplateException,
IOException
Processes the template to which this environment belongs.
setCurrentVisitorNode
public void setCurrentVisitorNode(TemplateNodeModel node)
sets TemplateNodeModel as the current visitor node. .current_node
setDateFormat
public void setDateFormat(String formatName)
Sets the date format used to convert date models representing date-only
dates to strings.
- setDateFormat in interface Configurable
setDateTimeFormat
public void setDateTimeFormat(String formatName)
Sets the date format used to convert date models representing datetime
dates to strings.
- setDateTimeFormat in interface Configurable
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)
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>
.
name
- the identifier of the variablemodel
- the value of the variable.
setLocale
public void setLocale(Locale locale)
Sets the locale to assume when searching for template files with no
explicit requested locale.
- setLocale in interface Configurable
setNumberFormat
public void setNumberFormat(String formatName)
Sets the number format used to convert numbers to strings.
- setNumberFormat in interface Configurable
setOut
public void setOut(Writer out)
setOutputEncoding
public void setOutputEncoding(String outputEncoding)
Sets the output encoding. Allows null
, which means that the
output encoding is not known.
- setOutputEncoding in interface Configurable
setTimeFormat
public void setTimeFormat(String formatName)
Sets the date format used to convert date models representing time-only
values to strings.
- setTimeFormat in interface Configurable
setTimeZone
public void setTimeZone(TimeZone timeZone)
Sets the time zone to use when formatting time values.
- setTimeZone in interface Configurable
setURLEscapingCharset
public void setURLEscapingCharset(String urlEscapingCharset)
Sets the URL escaping charset. Allows null
, which means that the
output encoding will be used for URL escaping.
- setURLEscapingCharset in interface Configurable
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)