Built-ins for booleans - 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

# Built-ins for booleans

## c (for boolean value)

Note:

The `c` built-in also works on numbers, and on strings!

Note:

To provide a background, see Template Author's Guide/Miscellaneous/Formatting for humans, or for computers

Note:

The `c` built-in supports booleans since FreeMarker 2.3.20.

This built-in converts a boolean to a "computer language" literal, as opposed to format it for human reading. This formats is independent of the `boolean_format` configuration setting, as that setting is meant to specify the format for human readers. Instead, it depends on the `c_format` setting. However, currently all `c_format` that's built into FreeMarker result will give `true` or `false`.

When outputting boolean literals for JavaScript, JSON, Java, and many other languages, always use this built-in, instead of relying on `boolean_format`.

If you only generate output that's computer language and isn't read by end-users, you may prefer to set the `boolean_format` configuration setting to `c` (since FreeMarker 2.3.29), in which case `${aBoolean}` will have the same output as `${aBoolean?c}`.

If the value the `c` built-in is applied on is `null`/missing, it will stop the template processing with error, just like most other built-ins. If instead you want to output a `null` literal, see the `cn` built-in.

## cn (for boolean value)

This does the same as the `c` built-in, but when applied on a `null`/missing value, it will output a `null` value according the `c_format` setting. See more details about formatting a `null` here.

## string (when used with a boolean value)

Converts a boolean to a string. You can use it in two ways:

- As `foo?string("yes", "no")`: Formats the boolean value to the first parameter (here: `"yes"`) if the boolean is true, and to the second parameter (here: `"no"`) if it's false. Unless you only meant to format a boolean with simple literals, use `?then(whenTrue, whenFalse)` instead, as that has less type limitations, and it evaluate its parameters lazily! The return value of `?string` is always a string (unlike for `?then`), because if the parameters aren't strings, they will be converted to strings. Also note that both parameters are evaluated (unlike for `?then`), despite that only one of them will be used; this might has negative impact if the parameters aren't just literals.

- `foo?string`: Deprecated starting from FreeMarker 2.3.20: use `?c` instead, or set the `boolean_format` setting to something like `"yes,no"` and then the conversion can happen automatically. If you still need to know about this, this will convert the boolean to string using the default strings for representing true and false values. By default, true is rendered as `"true"` and false is rendered as `"false"`. This is mostly only useful if you generate source code with FreeMarker (but use `?c` for that starting from 2.3.20). To change these default strings, you can use the `boolean_format` setting.

  Note that in the very rare case when a value is multi-typed and is both a boolean and a string, then the string value of the variable will be returned, and so the `boolean_format` setting will have no effect.

## then

Note:

This built-in exists since FreeMarker 2.3.23.

Used like `booleanExp?then(whenTrue, whenFalse)`, fills the same role as the ternary operator in C-like languages (i.e., `booleanExp ? whenTrue : whenFalse`). If `booleanExp` evaluates to boolean true then it evaluates and returns its first argument, or else if `booleanExp` evaluates to boolean false then it evaluates and return its second argument. Off course, all three expression can be arbitrary complex. The argument expressions can have any type, even different types.

An important special property of this built-in is that only one of the argument expressions will be evaluated. This is unlike with normal method calls, where all argument expressions are evaluated, regardless if the method will need them. This also means that the argument that's not needed can even refer to missing variables without causing error. (It still can't be syntactically invalid of course.)

Example:

Template

    <#assign foo = true>
    ${foo?then('Y', 'N')}

    <#assign foo = false>
    ${foo?then('Y', 'N')}

    <#assign x = 10>
    <#assign y = 20>
    <#-- Prints 100 plus the maximum of x and y: -->
    ${100 + (x > y)?then(x, y)}

Output

    Y

    N

    120

Note:

If you need to choose based on a non-boolean value, you should use the `switch` built-in instead of nesting multiple `then`-s into each other, like `priority?switch(1, "low", 2, "medium", 3, "high")`, or even `true?switch(priority <= 1, "low", priority == 2, "medium", priority >= 3, "high")`.

Previous Next