assign

Page Contents

Synopsis

<#assign name1=value1 name2=value2 ... nameN=valueN>
or
<#assign same as above... in namespacehash>
or
<#assign name>
  capture this
</#assign>
or
<#assign name in namespacehash>
  capture this
</#assign>

Where:

  • name: name of the variable. It is not expression. However, it can be written as a string literal, which is useful if the variable name contains reserved characters, for example <#assign "foo-bar" = 1>. Note that this string literal does not expand interpolations (as "${foo}"); if you need to assign to a dynamically constructed name, the you have to use a different trick. Note that because the FreeMarker template language assumes that sequences (lists, arrays, etc.) and hashes (maps, beans, etc.) are immutable, you can not write something like <#assign myObj.someProperty = 'will NOT work'> or <#assign myList[0] = 'will NOT work'>. However, adding sequences or hashes with the + operator to form another value is supported; see in the chapter about expressions, and please note the performance consequences.
  • =: Assignment operator. It can also be one of the assignment shorthand operators (since FreeMarker 2.3.23): ++, --, +=, -=, *=, /= or %=. Like <#assign x++> is similar to <#assign x = x + 1>, and <#assign x += 2> is the same as <#assign x = x + 2>. Note that ++ always means arithmetical addition (an so it will fail on non-numbers), unlike + or += that are overloaded to do string concatenation and such.
  • value: the value to store. Expression.
  • namespacehash: a hash that was created for a namespace (by import). Expression. If not specified, it defaults to the namespace that belongs to the containing template.

Description

With this you can create a new variable, or replace an existing variable. Note that only top-level variables can be created/replaced (i.e. you can't create/replace some_hash.subvar, but some_hash).

For more information about variables, read this: Template Author's Guide/Miscellaneous/Defining variables in the template

Note:

A frequent mistake is trying to use assign to change a local variable like: <#macro m><#local x = 1>${x}<#assign x = 2>${x}</#macro>. This prints 11, not 12, because assign creates/replaces the x of the namespace that the template belongs to, and doesn't change the x local variable. Local variables should be always set with the local directive, not just for the fist time.

Example: variable seq will store a sequence:

Template
<#assign seq = ["foo", "bar", "baz"]>

Example: Increments the numerical value stored in variable x:

Template
<#assign x++>

As a convenience feature, you can do more assignments with one assign tag. For example this will do the same as the two previous examples:

Template
<#assign
  seq = ["foo", "bar", "baz"]
  x++
>

If you know what namespaces are: assign directive creates variables in a namespace. Normally it creates the variable in the current namespace (i.e. in the namespace associated with the template where the tag is). However, if you use in namespacehash then you can create/replace a variable of another namespace than the current namespace. For example, here you create/replace variable bgColor of the namespace used for /mylib.ftl:

Template
<#import "/mylib.ftl" as my>
<#assign bgColor="red" in my>

An extreme usage of assign is when it captures the output generated between its start-tag and end-tag. That is, things that are printed between the tags will not be shown on the page, but will be stored in the variable. For example:

Template
<#macro myMacro>foo</#macro>
<#assign x>
  <#list 1..3 as n>
    ${n} <@myMacro />
  </#list>
</#assign>
Number of words: ${x?word_list?size}
${x}

will print:

Output
Number of words: 6
    1 foo
    2 foo
    3 foo

Please note that you should not to use this to insert variables into strings:

Template
<#assign x>Hello ${user}!</#assign> <#-- BAD PRACTICE! -->

You should simply write:

Template
<#assign x="Hello ${user}!">