Defining variables in the template

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 the assign. Also, because macros and functions are just variable, the macro directives and function directives also set variables like assign 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 to include-d. Thus, their visibility is like that of data-model variables.They are set via the global 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


FreeMarker Manual -- For FreeMarker 2.3.22 HTML generated: 2015-02-28 21:34:03 GMT