assign - Apache FreeMarker Manual

Unsupported web browser - Use a modern browser to view this website!

- Home
- Manual
- Java API

- Contribute
- Report a Bug
- Download

Manual
Previous Next

# assign

## 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}!">

Previous Next