As we have described, a template can use the variables defined in the data-model. A template can also define variables outside the data-model for its own use. These temporary variables can be created and replaced using FTL directives. Note that each template processing job has its own private set of these variables that exists while the given page is rendered. This variable set is initially empty, and will be thrown away when the template processing job has been finished.
You access a variable that you have defined in the template
exactly as if it were a variable in the data-model root. The variable
has precedence over any variable of the same name defined in the
data-model. That is, if you define a variable called ``foo'' and
coincidentally, there is a ``foo'' in the data-model as well, then the
variable created in the template will hide (not overwrite!) the
variable in the data-model root. For example,
${foo}
will print the value of the variable created
in the template.
There are 3 kind of variables that are defined in a template:
-
``plain'' variables: They are accessible from everywhere in the template, or from the templates inserted with
include
directive. You can create and replace these variables with theassign
. Also, because macros and functions are just variable, themacro
directives andfunction
directives also set variables likeassign
does. -
Local variables: They can only be set inside a macro definition body, and are only visible from there. A local variable only exists for the duration of a macro call. You can create and replace local variables inside macro definition bodies with the
local
directive. -
Loop variables: Loop variables are created automatically by directives like
list
, and they only exist between the start-tag and end-tag of the directive. Macro parameters are local variables, not loop variables. -
Global variables: This is an advanced topic, and this kind of variables should be seldom used. Global variables are shared by all templates, even if they belong to different name spaces because they were
import
-ed as opposed toinclude
-d. Thus, their visibility is like that of data-model variables.They are set via theglobal
directive.
Example: Create and replace variables with
assign
:
<#assign x = 1> <#-- create variable x --> ${x} <#assign x = x + 3> <#-- replace variable x --> ${x}
Output:
1 4
Local variables hide (not overwrite) ``plain'' variables of the same name. Loop variables hide (not overwrite) local and ``plain'' variables of the same name. For example:
<#assign x = "plain"> 1. ${x} <#-- we see the plain var. here --> <@test/> 6. ${x} <#-- the value of plain var. was not changed --> <#list ["loop"] as x> 7. ${x} <#-- now the loop var. hides the plain var. --> <#assign x = "plain2"> <#-- replace the plain var, hiding does not mater here --> 8. ${x} <#-- it still hides the plain var. --> </#list> 9. ${x} <#-- the new value of plain var. --> <#macro test> 2. ${x} <#-- we still see the plain var. here --> <#local x = "local"> 3. ${x} <#-- now the local var. hides it --> <#list ["loop"] as x> 4. ${x} <#-- now the loop var. hides the local var. --> </#list> 5. ${x} <#-- now we see the local var. again --> </#macro>
the output:
1. plain 2. plain 3. local 4. loop 5. local 6. plain 7. loop 8. loop 9. plain2
An inner loop variable can hide an outer loop variable:
<#list ["loop 1"] as x> ${x} <#list ["loop 2"] as x> ${x} <#list ["loop 3"] as x> ${x} </#list> ${x} </#list> ${x} </#list>
the output:
loop 1 loop 2 loop 3 loop 2 loop 1
Note that the value of a loop variable is set by the directive
invocation that has created it (the <list
...>
tags in this case). There
is no other way to change the value of a loop variable (say, you can't
change its value with some kind of assignment directive). You can hide
temporarily a loop variable with another loop variable though, as you
have seen above.
Sometimes it happens that a variable hides the variable in the
data-model with the same name, but you want to read the variable of
the data-model. In this case you can use the special variable
globals
. For example, assume we have a variable
called user
in the data-model with value ``Big
Joe'':
<#assign user = "Joe Hider"> ${user} <#-- prints: Joe Hider --> ${.globals.user} <#-- prints: Big Joe -->
Variables set via the global
directive hide data-model variables with the same name. Often,
global variables are set exactly for this purpose. But when not, you
can still access the data-model variable like
.data_model.user
.
For information about syntax of variables please read: The Template/Expressions