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

These built-ins act on a string left-value. However, if the left-value is number or date/time/date-time or boolean (since 2.3.20), it will automatically converted to string according the current number-, date/time/date-time- and boolean-format settings (which are the same formatters that are applied when inserting such values with `${...}`).

## boolean

The string converted to boolean value. The string must be `true` or `false` (case sensitive!), or must be in the format specified by the `boolean_format` setting.

If the string is not in the appropriate format, an error will abort template processing when you try to access this built-in.

## blank_to_null

Returns missing value (Java `null`) if the value is a string with 0 length, or contains only whitespace characters, or the value is missing (`null`, or an undefined variable). Otherwise it returns the string as is (without trimming). As it reduces blank strings to a missing value (Java `null`), this let's you uniformly handle blanks the same as missing values, with the missing value handler operators. For example, if somewhere you have `${user.fullName!'Not specified'}`, but then you realize that sometimes `user.fullName` is a blank string (which is not a missing value, hence the default value is not applied), you can fix that as `${user.fullName?blank_to_null!'Not specified'}`.

Example:

Template

    ${nonExisting?blank_to_null!"-"}
    ${""?blank_to_null!"-"}
    ${"    "?blank_to_null!"-"}

    ${"a"?blank_to_null!"-"}
    ${"  a  "?blank_to_null!"-"}.

The output:

Output

    -
    -
    -

    a
      a  .

Note that this built-in considers everything that's whitespace according to UNICODE as a blank character, including the various non-breaking whitespace variants (like `"\xA0"`, NBSP). This is in contrast with `trim` and ``trim_to_null``, which only considers ASCII whitespace as removable.

Note that this built-in behaves with parentheses on its left side as the missing value handler operators, that is, `(missingValue.subvariable)?blank_or_null` will handle `missingValue`, while `missingValue.subvariable?blank_or_null` will fail at the `.` (dot) operator.

See also: `empty_to_null`, ``trim_to_null``

## cap_first

The string with the very first word of the string capitalized. For the precise meaning of "word" see the word_list built-in. Example:

Template

    ${"  green mouse"?cap_first}
    ${"GreEN mouse"?cap_first}
    ${"- green mouse"?cap_first}

The output:

Output

      Green mouse
    GreEN mouse
    - green mouse

In the case of `"- green mouse"`, the first word is the `-`.

Note that this uses locale-aware conversion, that is, the result can be different depending on the current `locale` (language, country).

## c (for string value)

Note:

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

Note:

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

Note:

The `c` built-in supports strings since FreeMarker 2.3.32.

This built-in converts a string to a "computer language" literal, according the value of the `c_format` setting.

For the `c_format`-s that are built into FreeMarker the rules are the following:

- "JSON", "legacy": Gives a JSON string literal, that is, it will be surrounded with quotation marks (`"`), and will be escaped using backslash (`\`) where needed. For the exact escaping rules see the `json_string` built-in.

- "JavaScript": Almost the same as JSON, but uses `\xXX` instead of `\uXXXX` where possible. For the exact escaping rules see the `js_string` built-in, except that this won't escape the apostrophe quote (since it knows that it has used quotation marks around the string literal).

- "Java": Gives a Java string literal, that is, it will be surrounded with quotation marks (`"`), and will be escaped using backslash (`\`) where needed. For the exact escaping rules see the `j_string` built-in.

- "XS": Leaves the string as is. The idea is that you will insert the value as the body of an XML element, or into an XML attribute, so it needs no quotation, or any other special syntax. While it does need XML encoding, that should be handled by the automatic escaping facility, and not by the `c_format` facility.

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 string 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.

## c_lower_case

The string converted to lower case, for computer consumption ("c" as in the `c` built-in). Put simply, it will be converted to lower case as in English, regardless of the current `locale` (language, country). For example `"ITEM list"?c_lower_case` will be `"item list"`, always.

For lower case conversion for human consumption use the `lower_case` built-in instead!

## c_upper_case

The string converted to upper case, for computer consumption ("c" as in the `c` built-in). Put simply, it will be converted to upper case as in English, regardless of the current `locale` (language, country). For example `"ITEM list"?c_upper_case` will be `"ITEM LIST"`, always.

For upper case conversion for human consumption use the `upper_case` built-in instead!

## capitalize

The string with all words capitalized. For the precise meaning of "word" see the word_list built-in. Example:

Template

    ${"  green  mouse"?capitalize}
    ${"GreEN mouse"?capitalize}

The output:

Output

      Green Mouse
    Green Mouse

## chop_linebreak

Returns the string without the line-break at its very end if there was a line-break, otherwise the unchanged string. If the string ends with multiple line-breaks, only the last line-break is removed.

## contains

Note:

This built-in is available since FreeMarker 2.3.1. It doesn't exist in 2.3.

Returns if the substring specified as the parameter to this built-in occurrs in the string. For example:

Template

    <#if "piceous"?contains("ice")>It contains "ice"</#if>

This will output:

Output

    It contains "ice"

## date, time, datetime

The string value converted to a date, time, or date-time value. It will expect the format specified by the `date_format`, `time_format` and `datetime_format` settings. If the string is not in the appropriate format, an error will abort template processing when you try to access this built-in.

Template

    <#-- The date_format, time_format and datetime_format settings must match this format! -->
    <#assign someDate = "Oct 25, 1995"?date>
    <#assign someTime = "3:05:30 PM"?time>
    <#assign someDatetime = "Oct 25, 1995 03:05:00 PM"?datetime>

    <#-- Changing the setting value changes the expected format: -->
    <#setting datetime_format="iso">
    <#assign someDatetime = "1995-10-25T15:05"?datetime>

You can also specify the format explicitly like `?datetime.format` (and hence also as `?datetime["format"]`) or `?datetime("format")`; these three forms do the same. The format can be specified similarly with `?date` and `?time` too. For the syntax and meaning of format values see the possible values of the `date_format`, `time_format` and `datetime_format` settings. Example:

Template

    <#-- Parsing XML Schema xs:date, xs:time and xs:dateTime values: -->
    <#assign someDate = "1995-10-25"?date.xs>
    <#assign someTime = "15:05:30"?time.xs>
    <#assign someDatetime = "1995-10-25T15:05:00"?datetime.xs>

    <#-- Parsing ISO 8601 (both extended and basic formats): -->
    <#assign someDatetime = "1995-10-25T15:05"?datetime.iso>
    <#assign someDatetime = "19951025T1505"?datetime.iso>

    <#-- Parsing with SimpleDateFormat patterns: -->
    <#assign someDate = "10/25/1995"?date("MM/dd/yyyy")>
    <#assign someTime = "15:05:30"?time("HH:mm:ss")>
    <#assign someDatetime = "1995-10-25 03:05 PM"?datetime("yyyy-MM-dd hh:mm a")>

    <#-- Parsing with custom date formats: -->
    <#assign someDatetime = "October/25/1995 03:05 PM"?datetime.@worklog>

To prevent misunderstandings, the left-hand value need not be a string literal. For example, when you read data from XML DOM (from where all values come as unparsed strings), you may do things like `order.confirmDate?date.xs` to convert the string value to a real date.

Of course, the format also can be a variable, like in `"..."?datetime(myFormat)`.

Note that since 2.3.24, these built-ins can also be called with 0 arguments, like `?date()`. It's almost the same as just writing `?date`. The difference is highly technical and rarely matters: `?date()` and such returns exactly the same Java object that the date parser (`freemarker.core.TemplateDateFormat` implementation) returns, while `?date` without the `()` returns a tricky wrapper value that's a date and a method and hash on the same time.

## dedent

Note:

This built-in is available since FreeMarker 2.3.35.

Removes a leading prefix (usually indentation) from each line of the string. The built-in has two forms: a no-argument form that strips common leading whitespace automatically, and an explicit-prefix form for exact control. Line-breaks can be `LF` (Linux), or `CRLF` (DOS/Windows), even `CR` (old Mac), and are kept as is.

See also the `indent` built-in, which the inverse of this (roughly).

### No-argument form

The no-argument form (`?dedent`) finds the longest indentation (spaces and tabs only) that is a common prefix in all lines, and removes it. Lines that are empty or only contain spaces and tabs are treated specially; they don't influence the computation of the longest indentation, and will be replaced with an empty (line-break only) line in the output. (These semantics match Python's `textwrap.dedent`.)

For example:

Template

    <#assign code = "  if (x) {\n    foo();\n  }" />
    // <- touches left margin
    ${code?dedent}

will output this (the common indentation prefix was 2 spaces, which was now removed from each line):

Output

    // <- touches left margin
    if (x) {
      foo();
    }

A leading tab and a leading space are treated as distinct characters (we don't resolve tabs to space or vice versa).

### Explicit-prefix form

The explicit-prefix form (`?dedent(prefix)`) removes from each line the longest leading section of the `prefix` parameter that the line starts with. So for `?dedent("1234")`, the line "1234x" is reduced "x", and so are "123x", "12x", and "1x" too, as they start the same as "1234". But a line like "x1234x" or "234x", would remain unchanged. Use this form when you want to specify the amount of indentation to remove, rather than letting it be detected. For example:

Template

    <#assign code = "  if (x) {\n    foo();\n  }" />
    // <- touches left margin
    ${code?dedent(" ")}

will output this (removed just 1 space of indentation, so the 1st line still has 1 space of indentation, and the 2nd has 3 spaces of indentation):

Output

    // <- touches left margin
     if (x) {
       foo();
     }

With a 4-space prefix, lines that have less indentation than that simply lose all the indentation they have:

Template

    <#assign code = "  if (x) {\n    foo();\n  }" />
    // <- touches left margin
    ${code?dedent("    ")}

will output this (the 2nd line had 4 spaces, so all 4 were removed; the other lines only had 2, so those 2 were removed):

Output

    // <- touches left margin
    if (x) {
    foo();
    }

Note:

Partial matches are shortened rather than ignored on purpose. This is what's familiar from code text editors, when you repeatedly dedent a block of text, and some lines already have too low indentation. Also, an all-or-nothing dedent could leave a line that was originally the least indented as the most indented one, which is a more confusing result than partially flattening indentation hierarchy.

All `dedent(prefix)` removes the trailing whitespace of each resulting line. (As a result, if after removing a prefix a line only contains whitespace, it becomes an empty line.) To disable trimming, set the optional 2nd parameter to `false`:

Template

    ${code?dedent("    ", false)}

Notes on trailing whitespace removal:

- Whitespace there means any UNICODE whitespace, and does not include non-breaking space.

- If the provided prefix argument is a 0-length string, then `dedent` will return the string as is, and will not trim the lines.

## empty_to_null

Returns missing value (Java `null`) if the value is a string with 0 length, or the value is missing (`null`, or an undefined variable). Otherwise it returns the string as is (without trimming). As it reduces empty strings to a missing value (Java `null`), this let's you uniformly handle empty strings the same as missing values, with the missing value handler operators. For example, if somewhere you have `${user.fullName!'Not specified'}`, but then you realize that sometimes `user.fullName` is an 0-length string (which is not a missing value, hence the default value is not applied), you can fix that as `${user.fullName?empty_to_null!'Not specified'}`.

Example:

Template

    ${nonExisting?empty_to_null!"-"}
    ${""?empty_to_null!"-"}

    ${"    "?empty_to_null!"-"}.
    ${"a"?empty_to_null!"-"}
    ${"  a  "?empty_to_null!"-"}.

The output:

Output

    -
    -

        .
    a
      a  .

Note that this built-in behaves with parentheses on its left side as the missing value handler operators, that is, `(missingValue.subvariable)?empty_to_null` will handle `missingValue`, while `missingValue.subvariable?empty_to_null` will fail at the `.` (dot) operator.

See also: `blank_to_null`, ``trim_to_null``

## ends_with

Returns whether this string ends with the substring specified in the parameter. For example `"ahead"?ends_with("head")` returns boolean `true`. Also, `"head"?ends_with("head")` will return `true`.

## ensure_ends_with

Note:

This built-in is available since FreeMarker 2.3.21.

If the string doesn't end with the substring specified as the 1st parameter, it adds it after the string, otherwise it returns the original string. For example, both `"foo"?ensure_ends_with("/")` and `"foo/"?ensure_ends_with("/")` returns `"foo/"`.

## ensure_starts_with

Note:

This built-in is available since FreeMarker 2.3.21.

If the string doesn't start with the substring specified as the 1st parameter, it adds it before the string, otherwise it returns the original string. For example, both `"foo"?ensure_starts_with("/")` and `"/foo"?ensure_starts_with("/")` returns `"/foo"`.

If you specify two parameters, then the 1st parameter is interpreted as a Java regular expression, and if it doesn't match the beginning of the string, then the string specified as the 2nd parameter is added before the string. For example `someURL?ensure_starts_with("[a-zA-Z]+://", "http://")` will check if the string starts with something that matches `"[a-zA-Z]+://"` (note that no `^` is needed), and if it doesn't, it prepends `"http://"`.

This method also accepts a 3rd flags parameter. As calling with 2 parameters implies `"r"` there (i.e., regular expression mode), you rarely need this. One notable case is when you don't want the 1st parameter to be interpreted as a regular expression, only as plain text, but you want the comparison to be case-insensitive, in which case you would use `"i"` as the 3rd parameter.

## esc

Note:

This built-in is available since FreeMarker 2.3.24.

Escapes the value with the current output format, and prevents the auto-escaping of the returned value (to avoid double escaping). Because of auto-escaping, you usually only need this where auto-escaping was disabled:

Template

    <#ftl output_format="HTML" auto_esc=false>
    <#assign s = "R&D">
    ${s}
    ${s?esc}

Output

    R&D
    R&amp;D

In templates, where auto-escaping is on, using it is redundant:

Template

    <#ftl output_format="HTML">
    <#assign s = "R&D">
    ${s}
    ${s?esc} <#-- ?esc is redundant here -->

Output

    R&amp;D
    R&amp;D

This built-in works by converting the string value to a markup output value, by escaping the string with the current output format, and using the result as the markup. The resulting markup output value belongs to the current output format at the point of the invocation.

This built-in can also be applied on markup output values, which it will bypass without change, as far as the input markup output value belongs to the current output format. If it doesn't, then the markup has to be converted to the current output format, which currently (as of 2.3.24) will be only successful if that value was created by escaping plain text (usually, with `?esc`).

This built-in can't be used where the current output format is a non-markup output format. An attempt to do so will cause a parse-time error.

This built-in is not related to the deprecated `escape` and `noescape` directives. In fact, the parser will prevent using them on the same place, to prevent confusion.

## groups

This is used only with the result of the `matches` built-in. See there...

## html (deprecated)

Note:

This built-in is deprecated by the auto-escaping mechanism introduced in 2.3.24. To prevent double escaping and confusion in general, using this built-in on places where auto-escaping is active is a parse-time error. To help migration, this built-in silently bypasses HTML markup output values without changing them.

The string as HTML markup. That is, the string with all:

- `<` replaced with `&lt;`
- `>` replaced with `&gt;`
- `&` replaced with `&amp;`
- `"` replaced with `&quot;`
- `'` is replaced with `&#39;` if the programmers has set the `incompatible_improvements` setting to 2.3.24 or higher (also if it's set to 2.3.20 or higher and you are outside a string literal). Otherwise `'` won't be replaced, so you must use quotation mark (`"`, not `'`) to quote attribute values where you want to insert a value safely.

Template

    <input type=text name=user value="${user?html}">

Warning!

When inserting the value of an attribute, always quote it, or else it can be exploited by attackers! This is WRONG: `<input name="user" value=${user?xhtml}>`. This is good: `<input name="user" value="${user?xhtml}">`.

Note that in HTML pages usually you want to use this built-in for all interpolations. You can spare a lot of typing and lessen the chances of accidental mistakes by using the `escape` directive.

## indent

Note:

This built-in is available since FreeMarker 2.3.35.

Prepends the string given as the 1st parameter to the beginning of each line, then removes the trailing whitespace of each resulting line (unless that's switched off with the 2nd parameter). The 1st parameter is most often some spaces or tabs used for indentation, but can be any string. Line-breaks can be `LF` (Linux), or `CRLF` (DOS/Windows), even `CR` (old Mac), and are kept as is.

See also the `dedent` built-in, which the inverse of this (roughly).

Example of indenting each line with 4 spaces:

Template

    <#assign code = "int x;\nint y;" />
    // <- touches left margin
    ${code?indent("    ")}

will output this :

Output

    // <- touches left margin
        int x;
        int y;

Another example, using a non-whitespace prefix:

Template

    <#assign text = "First line.\nSecond line." />
    ${text?indent(" * ")}

will output this:

Output

     * First line.
     * Second line.

The prefix is added to every line, including lines that are empty or contain whitespace only. That would leave a trailing prefix on such lines, which is why the trailing whitespace of each line is removed afterwards. Consider commenting out a block of text with a `"# "` prefix:

Template

    <#assign text = "First paragraph.\n\nSecond paragraph." />
    ${text?indent("# ")}

will output this, where the empty line became `"#"` rather than `"# "`, as the space in `"# "` was only meant to separate the prefix from the content of a line:

Output

    # First paragraph.
    #
    # Second paragraph.

With a whitespace-only prefix this leaves empty lines empty, so the trimming is only visible with prefixes like the above. It also means that lines that are empty and lines that only contain whitespace give the same result, and that accidental trailing whitespace is removed from the other lines as well.

Set the optional 2nd parameter to `false` to switch the trimming off, and thus get the prefix on every line verbatim:

Template

    ${text?indent("# ", false)}

Note:

A non-breaking space (`U+00A0`) isn't treated as whitespace when trimming, so it's kept; that's the purpose of a non-breaking space.

Notes on trailing whitespace removal:

- Whitespace there means any UNICODE whitespace, and does not include non-breaking space.

- If the provided prefix argument is a 0-length string, then `ident` will return the string as is, and will not trim the lines.

## index_of

Returns the index within this string of the first occurrence of the specified substring. For example, `"abcabc"?index_of("bc")` will return 1 (don't forget that the index of the first character is 0). Also, you can specify the index to start the search from: `"abcabc"?index_of("bc", 2)` will return 4. There is no restriction on the numerical value of the second parameter: if it is negative, it has the same effect as if it were zero, and if it is greater than the length of this string, it has the same effect as if it were equal to the length of this string. Decimal values will be truncated to integers.

If the 1st parameter does not occur as a substring in this string (starting from the given index, if you use the second parameter), then it returns -1.

## j_string

Escapes the string with the escaping rules of Java language string literals, so it's safe to insert the value into a string literal. Note that it will not add quotation marks around the inserted value; you meant to use this inside the string literal.

All characters under UCS code point 0x20 will be escaped. When they have no dedicated escape sequence in the Java language (like `\n`, `\t`, etc.), they will be replaced with a UNICODE escape (`\uXXXX`).

Example:

Template

    <#assign beanName = 'The "foo" bean.'>
    String BEAN_NAME = "${beanName?j_string}";

will output:

Output

    String BEAN_NAME = "The \"foo\" bean.";

## js_string

Escapes the string with the escaping rules of JavaScript language string literals, so it's safe to insert the value into a string literal. Note that it will not add quotation marks around the inserted value; you meant to use this inside the string literal.

Warning!

When inserting into a JavaScript string literal that's inside a HTML attribute, you also must escape the value with HTML escaping. Thus, of you don't have automatic HTML escaping, this is WRONG: `<p onclick="alert('${message?js_string}')">`, and this is good: `<p onclick="alert('${message?js_string?html}')">`.

Example:

Template

    <#assign user = "Big Joe's \"right hand\"">
    <script>
      alert("Welcome ${user?js_string}!");
    </script>

will output:

Output

    <script>
      alert("Welcome Big Joe\'s \"right hand\"!");
    </script>

The exact escaping rules are:

- `"` is escaped as `\"`

- `'` is escaped as `\'`

- `\` is escaped as `\\`

- `/` is escaped as `\/` if the `/` is directly after `<` in the escaped string, or if it's at the beginning of the escaped string

- `>` is escaped as `\>` if the `>` is directly after `]]` or `--` in the escaped string, or if it's at the beginning of the escaped string, or if there's only a `]` or `-` before it at the beginning of the escaped string

- `<` is escaped as `\u003C` if it's followed by `?` or `!` in the escaped string, or if it's at the end of the escaped string

- Control characters in UCS code point ranges U+0000...U+001f and U+007f...U+009f are escaped as `\r`, `\n`, etc., or as `\xXX` where there's no special escape for them in JavaScript.

- Control characters with UCS code point U+2028 (Line separator) and U+2029 (Paragraph separator) are escaped as `\uXXXX`, as they are source code line-breaks in ECMAScript.

## json_string

Escapes the string with the escaping rules of JSON language string literals, so it's safe to insert the value into a string literal. Note that it will not add quotation marks around the inserted value; you meant to use this inside the string literal.

This will not escape `'` characters, since JSON strings must be quoted with `"`.

The escaping rules are almost identical to those documented for `js_string`. The differences are that `'` is not escaped at all, that `>` is escaped as `\u003E` (not as `\>`), and that `\uXXXX` escapes are used instead of `\xXX` escapes.

## keep_after

Note:

This built-in is available since FreeMarker 2.3.21.

Removes the part of the string that is not after the first occurrence of the given substring. For example:

Template

    ${"abcdefgh"?keep_after("de")}

will print

Output

    fgh

If the parameter string is not found, it will return an empty string. If the parameter string is a 0-length string, it will return the original string unchanged.

This method accepts an optional flags parameter, as its 2nd parameter:

Template

    ${"foo : bar"?keep_after(r"\s*:\s*", "r")}

will print

Output

    bar

## keep_after_last

Note:

This built-in is available since FreeMarker 2.3.22.

Same as `keep_after`, but keeps the part after the last occurrence of the parameter, rather than after the first. Example:

Template

    ${"foo.bar.txt"?keep_after_last(".")}

will print

Output

    txt

while with `keep_after` you would get `bar.txt`.

## keep_before

Note:

This built-in is available since FreeMarker 2.3.21.

Removes the part of the string that starts with the given substring. For example:

Template

    ${"abcdef"?keep_before("de")}

will print

Output

    abc

If the parameter string is not found, it will return the original string unchanged. If the parameter string is a 0-length string, it will return an empty string.

This method accepts an optional flags parameter, as its 2nd parameter:

Template

    ${"foo : bar"?keep_before(r"\s*:\s*", "r")}

will print

Output

    foo

## keep_before_last

Note:

This built-in is available since FreeMarker 2.3.22.

Same as `keep_before`, but keeps the part before the last occurrence of the parameter, rather than after the first. Example:

Template

    ${"foo.bar.txt"?keep_before_last(".")}

will print

Output

    foo.bar

while with `keep_before` you would get `foo`.

## last_index_of

Returns the index within this string of the last (rightmost) occurrence of the specified substring. It returns the index of the first (leftmost) character of the substring. For example: `"abcabc"?last_index_of("ab")` will return 3. Also, you can specify the index to start the search from. For example, `"abcabc"?last_index_of("ab", 2)` will return 0. Note that the second parameter indicates the maximum index of the start of the substring. There is no restriction on the numerical value of the second parameter: if it is negative, it has the same effect as if it were zero, and if it is greater than the length of this string, it has the same effect as if it were equal to the length of this string. Decimal values will be truncated to inegers.

If the 1st parameter does not occur as a substring in this string (before the given index, if you use the second parameter), then it returns -1.

## left_pad

Note:

This built-in is available since FreeMarker 2.3.1.

If it's used with 1 parameter, then it inserts spaces on the beginning of the string until it reaches the length that is specified as the parameter. If the string is already as long or longer than the specified length, then it does nothing. For example, this:

Template

    [${""?left_pad(5)}]
    [${"a"?left_pad(5)}]
    [${"ab"?left_pad(5)}]
    [${"abc"?left_pad(5)}]
    [${"abcd"?left_pad(5)}]
    [${"abcde"?left_pad(5)}]
    [${"abcdef"?left_pad(5)}]
    [${"abcdefg"?left_pad(5)}]
    [${"abcdefgh"?left_pad(5)}]

will output this:

Output

    [     ]
    [    a]
    [   ab]
    [  abc]
    [ abcd]
    [abcde]
    [abcdef]
    [abcdefg]
    [abcdefgh]

If it's used with 2 parameters, then the 1st parameter means the same as if you were using the built-in with only 1 parameter, and the second parameter specifies what to insert instead of space characters. For example:

Template

    [${""?left_pad(5, "-")}]
    [${"a"?left_pad(5, "-")}]
    [${"ab"?left_pad(5, "-")}]
    [${"abc"?left_pad(5, "-")}]
    [${"abcd"?left_pad(5, "-")}]
    [${"abcde"?left_pad(5, "-")}]

will output this:

Output

    [-----]
    [----a]
    [---ab]
    [--abc]
    [-abcd]
    [abcde]

The 2nd parameter can be a string whose length is greater than 1. Then the string will be inserted periodically, for example:

Template

    [${""?left_pad(8, ".oO")}]
    [${"a"?left_pad(8, ".oO")}]
    [${"ab"?left_pad(8, ".oO")}]
    [${"abc"?left_pad(8, ".oO")}]
    [${"abcd"?left_pad(8, ".oO")}]

will output this:

Output

    [.oO.oO.o]
    [.oO.oO.a]
    [.oO.oOab]
    [.oO.oabc]
    [.oO.abcd]

The 2nd parameter must be a string value, and it must be at least 1 character long.

## length

The number of characters in the string.

## lower_case

The lower case version of the string, using rules that depend on the current `locale` (language, country). For example `"KARIŞIK işaretler"?lower_case` will be `"karişik işaretler"` in most locales, but will be `"karışık işaretler"` in Turkish (`tr_TR`) locale (note the missing dot above some of the "i"-s).

To convert to lower case for computer consumption (as opposed to human consumption), use the `c_lower_case` built-in instead!

## lines

Note:

This built-in is available since FreeMarker 2.3.35.

Splits the string at the line breaks to a sequence of lines. The resulting lines themselves don't contain the line-break character. All kind of line-breaks are recognized: `LF` (Linux), or `CRLF` (DOS/Windows), even `CR` (old Mac).

Example:

Template

    <#assign text = "Line 1\nLine 2\Line 3\n">
    <#list text?lines as line>
      - ${line}
    </#list>

will output:

Output

    - Line 1
    - Line 2
    - Line 3

The basic approach is that each line should end with a line-break, including the last line. But if the text doesn't end with line-break, then it's implied to have line-break at the end. Therefore, with `<#assign text = "Line 1\nLine 2\Line 3">` (no `\n` at the end), you would get the same output like above.

With `<#assign text = "Line 1\nLine 2\Line 3\n\n">` (two `\n`-s at the end), you would get and additional empty line in the output.

## matches

This is a "power user" built-in. Ignore it if you don't know regular expressions.

This built-in determines if the string exactly matches the pattern. Also, it returns the list of matching sub-strings. The return value is a multi-type value:

- Boolean: `true`, if it the entire string matches the pattern, otherwise `false`. For example, `"fooo"?matches('fo*')` is `true`, but `"fooo bar"?matches('fo*')` is `false`.

- Sequence: the list of matched substrings of the string. Possibly a 0 length sequence.

For example:

Template

    <#if "fxo"?matches("f.?o")>Matches.<#else>Does not match.</#if>

    <#assign res = "foo bar fyo"?matches("f.?o")>
    <#if res>Matches.<#else>Does not match.</#if>
    Matching sub-strings:
    <#list res as m>
    - ${m}
    </#list>

will print:

Output

    Matches.

    Does not match.
    Matching sub-strings:
    - foo
    - fyo

If the regular expression contains groups (parentheses), then you can access them with the `groups` built-in:

Template

    <#-- Entire input match -->
    <#assign res = "John Doe"?matches(r"(\w+) (\w+)")>
    <#if res> <#-- Must not try to access groups if there was no match! -->
      First name: ${res?groups[1]}
      Second name: ${res?groups[2]}
    </#if>

    <#-- Subtring matches -->
    <#assign res = "aa/rx; ab/r;"?matches("(.+?)/*(.+?);")>
    <#list res as m>
      - "${m}" is "${m?groups[1]}" per "${m?groups[2]}"
    </#list>

This will print:

Output

      First name: John
      Second name: Doe

      - "aa/rx;" is "a" per "a/rx"
      - " ab/r;" is " " per "ab/r"

Notes regarding the behavior of the `groups` built-in:

- It works both with substring matches and with the result of entire string matching (as it was shown in the above example)

- The first item in the sequence that `groups` returns is the whole substring matched by the regular expression. Hence, the index of the first explicit regular expression group (with other words, of the first `(...)` in the regular expression) is 1, and not 0. Also, because of this, the size of the sequence is one more than the number of explicit regular expression groups.

- The size of the sequence returned by `groups` only depends on the number of explicit groups in the regular expression, and so it will be the same (non-0) even if there was no match found for the regular expression. Attempting to access an item of the sequence (as in `res?groups[1]`) when there was match will cause an error. Thus, before accessing the groups, you should always check if there was any match (as in `<#if res>access the groups here</#if>`).

- When there's a match for the regular expression, but not for a certain explicit group inside the regular expression, then for that group the sequence will contain a 0 length string. So accessing a group that matches nothing is safe, as far as the containing regular expression has matched something.

`matches` accepts an optional 2nd parameter, the flags. Note that it doesn't support flag `f`, and ignores the `r` flag.

## no_esc

Note:

This built-in is available since FreeMarker 2.3.24.

Prevents the auto-escaping of a value. For example:

Template

    <#ftl output_format="HTML">
    <#assign s = "<b>Test</b>">
    ${s}
    ${s?no_esc}

Output

    &lt;b&gt;Test&lt;/b&gt;
    <b>Test</b>

This works by converting the string value to a markup output value, which uses the string as the markup as is, and belongs to the current output format at the point of the invocation.

This built-in can also be applied on markup output values, which it will bypass without change, as far as the input markup output value belongs to current output format. If it doesn't, then the markup has to be converted to the current output format, which currently (as of 2.3.24) will be only successful if that value was created by escaping plain text (usually, with `?esc`).

This built-in can't be used where the current output format is a non-markup output format. An attempt to do so will cause a parse-time error.

This built-in is not related to the deprecated `escape` and `noescape` directives. In fact, the parser will prevent using them on the same place, to prevent confusion.

## number

The string converted to numerical value. The number must be in "computer language" format. That is, it must be in the locale independent form, where the decimal separator is dot, and there's no grouping.

This built-in recognizes numbers in the format that the FreeMarker template language uses. In additionally, it recognizes scientific notation (e.g. `"1.23E6"`, `"1.5e-8"`). Since FreeMarker 2.3.21, it also recognizes all XML Schema number formats, like `NaN`, `INF`, `-INF`, plus the Java-native formats `Infinity` and `-Infinity`.

If the string is not in the appropriate format, an error will abort template processing when you try to access this built-in.

In fact, the string is parsed by the `toNumber` method of the current `arithmetic_engine`, which is configuration setting. However, that method should behave similarly as described above.

## replace

It is used to replace all occurrences of a string in the original string with another string. It does not deal with word boundaries. For example:

Template

    ${"this is a car acarus"?replace("car", "bulldozer")}

will print:

Output

    this is a bulldozer abulldozerus

The replacing occurs in left-to-right order. This means that this:

Template

    ${"aaaaa"?replace("aaa", "X")}

will print:

Output

    Xaa

If the 1st parameter is an empty string, then all occurrences of the empty string will be replaced, like `"foo"?replace("","|")` will evaluate to `"|f|o|o|"`.

`replace` accepts an optional flags parameter, as its 3rd parameter.

## right_pad

Note:

This built-in is available since FreeMarker 2.3.1. It doesn't exist in 2.3.

This is the same as `left_pad`, but it inserts the characters at the end of the string instead of the beginning of the string.

Example:

Template

    [${""?right_pad(5)}]
    [${"a"?right_pad(5)}]
    [${"ab"?right_pad(5)}]
    [${"abc"?right_pad(5)}]
    [${"abcd"?right_pad(5)}]
    [${"abcde"?right_pad(5)}]
    [${"abcdef"?right_pad(5)}]
    [${"abcdefg"?right_pad(5)}]
    [${"abcdefgh"?right_pad(5)}]

    [${""?right_pad(8, ".oO")}]
    [${"a"?right_pad(8, ".oO")}]
    [${"ab"?right_pad(8, ".oO")}]
    [${"abc"?right_pad(8, ".oO")}]
    [${"abcd"?right_pad(8, ".oO")}]

This will output this:

Output

    [     ]
    [a    ]
    [ab   ]
    [abc  ]
    [abcd ]
    [abcde]
    [abcdef]
    [abcdefg]
    [abcdefgh]

    [.oO.oO.o]
    [aoO.oO.o]
    [abO.oO.o]
    [abc.oO.o]
    [abcdoO.o]

## remove_beginning

Note:

This built-in is available since FreeMarker 2.3.21.

Removes the parameter substring from the beginning of the string, or returns the original string if it doesn't start with the parameter substring. For example:

Template

    ${"abcdef"?remove_beginning("abc")}
    ${"foobar"?remove_beginning("abc")}

will print:

Output

    def
    foobar

## remove_ending

Note:

This built-in is available since FreeMarker 2.3.21.

Removes the parameter substring from the ending of the string, or returns the original string if it doesn't end with the parameter substring. For example:

Template

    ${"abcdef"?remove_ending("def")}
    ${"foobar"?remove_ending("def")}

will print:

Output

    abc
    foobar

## rtf (deprecated)

Note:

This built-in is deprecated by the auto-escaping mechanism introduced in 2.3.24. To prevent double escaping and confusion in general, using this built-in on places where auto-escaping is active is a parse-time error. To help migration, this built-in silently bypasses RTF markup output values without changing them.

The string as Rich text (RTF text). That is, the string with all:

- `\` replaced with `\\`

- `{` replaced with `\{`

- `}` replaced with `\}`

## split

It is used to split a string into a sequence of strings along the occurrences of another string. For example:

Template

    <#list "someMOOtestMOOtext"?split("MOO") as x>
    - ${x}
    </#list>

will print:

Output

    - some
    - test
    - text

Note that it is assumed that all occurrences of the separator is before a new item (except with `"r"` flag - see later), thus:

Template

    <#list "some,,test,text,"?split(",") as x>
    - "${x}"
    </#list>

will print:

Output

    - "some"
    - ""
    - "test"
    - "text"
    - ""

`split` accepts an optional flags parameter, as its 2nd parameter. There's a historical glitch with the `r` (regular expression) flag; it removes the empty elements from the end of the resulting list, so with `?split(",", "r")` in the last example the last `""` would be missing from the output.

If the 1st parameter is an empty string, the string will be split to characters (since FreeMarker 2.3.28 - earlier this has only worked with the `r` flag).

Note:

To check if a strings ends with something and append it otherwise, use the `ensure_ends_with` built-in.

## starts_with

Returns if this string starts with the specified substring. For example `"redirect"?starts_with("red")` returns boolean `true`. Also, `"red"?starts_with("red")` will return `true`.

Note:

To check if a strings starts with something and prepend it otherwise, use the `ensure_starts_with` built-in.

## string (when used with a string value)

Does nothing, just returns the string as-is. The exception is that if the value is a multi-type value (e.g. it is both string and sequence at the same time), then the resulting value will be only a simple string, not a multi-type value. This can be utilized to prevent the artifacts of multi-typing.

## substring (deprecated)

Note:

This built-in is deprecated since FreeMarker 2.3.21 by slicing expressions, like `str[from..<toExclusive]`, `str[from..]`, and `str[from..*maxLength]`.

A warning if you are processing XML: Since slicing expressions work both for sequences and strings, and since XML nodes are typically both sequences and strings at the same time, there the equivalent expression is `someXmlNode?string[from..<toExclusive]` and `exp?string[from..]`, as without `?string` it would slice the node sequence instead of the text value of the node.

Note:

Some of the typical use-cases of string slicing is covered by convenient built-ins: `remove_beginning`, `remove_ending`, `keep_before`, `keep_after`, `keep_before_last`, `keep_after_last`

Synopsis: `exp?substring(from, toExclusive)`, also callable as `exp?substring(from)`

A substring of the string. `from` is the index of the first character. It must be a number that is at least 0 and less than or equal with `toExclusive`, or else an error will abort the template processing. The `toExclusive` is the index of the character position after the last character of the substring, or with other words, it is one greater than the index of the last character. It must be a number that is at least 0 and less than or equal to the length of the string, or else an error will abort the template processing. If the `toExclusive` is omitted, then it defaults to the length of the string. If a parameter is a number that is not an integer, only the integer part of the number will be used.

Example:

Template

    - ${'abc'?substring(0)}
    - ${'abc'?substring(1)}
    - ${'abc'?substring(2)}
    - ${'abc'?substring(3)}

    - ${'abc'?substring(0, 0)}
    - ${'abc'?substring(0, 1)}
    - ${'abc'?substring(0, 2)}
    - ${'abc'?substring(0, 3)}

    - ${'abc'?substring(0, 1)}
    - ${'abc'?substring(1, 2)}
    - ${'abc'?substring(2, 3)}

The output:

Output

    - abc
    - bc
    - c
    -

    -
    - a
    - ab
    - abc

    - a
    - b
    - c

## trim

The string without leading and trailing white-space. Example:

Template

    (${"  green mouse  "?trim})

The output:

Output

    (green mouse)

## trim_to_null

Similar to the `trim` built-in, but when the result is an empty string, it instead returns a missing value (Java `null`). Also, if the value to trim is missing (Java `null`, or an undefined variable), it returns a missing value (Java `null`) instead of failing (while the `trim` built-in will fail then). As it reduces blank strings to a missing value (Java `null`), this let's you uniformly handle blanks the same as missing values, with the missing value handler operators. For example, if somewhere you have `${user.fullName!'Not specified'}`, but then you realize that sometimes `user.fullName` is a blank string (which is not a missing value, hence the default value is not applied), and you also want to get rid of leading and trailing whitespace in non-blank values, then you can do that in one move as `${user.fullName?trim_to_null!'Not specified'}`.

Example:

Template

    ${nonExisting?trim_to_null!"-"}
    ${""?trim_to_null!"-"}
    ${"    "?trim_to_null!"-"}

    ${"a"?trim_to_null!"-"}
    ${"  a  "?trim_to_null!"-"}.

The output:

Output

    -
    -
    -

    a
    a.

Note that this built-in behaves with parentheses on its left side as the missing value handler operators, that is, `(missingValue.subvariable)?trim_to_null` will handle `missingValue`, while `missingValue.subvariable?trim_to_null` will fail at the `.` (dot) operator.

See also: `blank_to_null`, `empty_to_null`.

## truncate, truncate_...

Note:

If you just want to limit the length of string with straightforward behavior, then do not use this built in, but the sequence slicing, and ..* length limited range operators. For example, `s[0 ..* 10]` will give the first 10 characters of `s`, if `s` is longer than that, otherwise it just gives `s` as is. While `s?truncate(10, '')` expresses similar intent, it has complicated rules to give a result that looks nicer for humans, like it trims the right side at the cut, and sometimes cuts a bit early to avoid cutting into the last word.

Cuts off the end of a string if that's necessary to keep it under the length given as parameter, and appends a terminator string (`[...]` by default) to indicate that the string was truncated. Example (assuming default FreeMarker configuration settings):

Template

    <#assign shortName='This is short'>
    <#assign longName='This is a too long name'>
    <#assign difficultName='This isoneveryverylongword'>

    No truncation needed:
    ${shortName?truncate(16)}

    Truncated at word boundary:
    ${longName?truncate(16)}

    Truncated at "character boundary":
    ${difficultName?truncate(16)}

Output

    No truncation needed:
    This is short

    Truncated at word boundary:
    This is a [...]

    Truncated at "character boundary":
    This isonev[...]

Notes on some tricky aspects for truncation:

- The string is returned as is if its length doesn't exceed the specified length (16 in this case).

- When the string exceeded that length, its end was cut off in a way so that together with the added terminator string (`[...]` here) its length won't exceed 16. The result length is possibly shorter than 16, for the sake of better look (see later). Actually, the result length can also be longer than the parameter length, when the desired length is shorter than the terminator string alone, in which case the terminator is still returned as is. Also, an algorithm other than the default might choses to return a longer string, as the length parameter is in principle just a hint for the desired visual length.

- `truncate` prefers cutting at word boundary, rather than mid-word, however, if doing so would give a result that's shorter than the 75% of the length specified with the argument, it falls back to cut mid-word. In the last line of the above example, "This [...]" would be too short (11 < 16 * 75%), so it was cut mid-word instead.

- If the cut happened at word boundary, there's a space between the word end and the terminator string, otherwise there's no space between them. Only whitespace is treated as word separator, not punctuation, so this generally gives intuitive results. (Except, if the terminator string is set to be 0 length, no space is added before it, starting from FreeMarker 2.3.33.)

- Before adding the terminator string (possibly with a word boundary space before it, as explained above) after the string whose length was already cut, trailing whitespace is removed from that. For example `'1 67890A'?truncate(10)`, where there are 4 spaces between the `1` and `6`, will give "`1 [...]`" (7 characters), not "`1 [...]`" (10 characters).

### Adjusting truncation rules

Truncation rules are highly configurable by setting the `truncate_builtin_algorithm` configuration setting. This can be done by the programmers, not template authors, so for more details and examples please see the JavaDoc of Configurable.setTruncateBuiltinAlgorithm.

Truncation rules can also be influenced right in the template to a smaller extent:

- Specifying if the truncation should happen at word boundary or not:

  - `truncate_w` will always truncate at word boundary. For example, `difficultName?truncate_w(16)` returns "This [...]", rather than "This isonev[...]" (as saw in earlier example).

  - `truncate_c` will truncate at any character, not just at word ends. For example, `longName?truncate_c(16)` returns "This is a t[...]", rather than "This is a [...]" (as saw in earlier example). This tends to give a string length closer to the length specified, but still not an exact length, as it removes white-space before the terminator string, and re-adds a space if we are just after the end of a word, etc. (Except, space is not re-added if the terminator string is set to be 0 length, starting from FreeMarker 2.3.33.) If you need exact length, simply use `longName[0 ..* 16]`.

- Specifying the terminator string (instead of relying on its default): `truncate` and all `truncate_...` built-ins have an optional 2nd parameter for that. After that, a further optional parameter can specify the assumed length of the terminator string (otherwise its real length will be used). If you find yourself specifying the terminator string often, then certainly the defaults should be configured instead (via `truncate_builtin_algorithm configuration` - see earlier). Example:

  Template

      ${longName?truncate(16, '...')}
      ${longName?truncate(16, '...', 1)}

  Output

      This is a ...
      This is a too ...

  When the terminator string starts with dot (`.`) or ellipsis (`…`), the default algorithm will remove the dots and ellipses that the terminator touches, to prevent ending up with more than 3 dots at the end:

  Template

      ${'Foo bar.baaz'?truncate(11, '---')}
      ${'Foo bar.baaz'?truncate(11, '...')} (Not "Foo bar....")
      ${'Fo bar. baaz'?truncate(11, '...')} (Word separator space prevents touching)

  Output

      Foo bar.---
      Foo bar... (Not "Foo bar....")
      Fo bar. ... (Word separator space prevents touching)

### Using markup as terminator string

Each truncation built-in has a variation whose name ends with `_m` (for markup). These allow using markup (like HTML) as terminator, which is useful if you want the terminator to be styled differently than the truncated text. By default the markup terminator is `<span class='truncateTerminator'>[&#8230;]</span>`, (where `&#8230;` prints an ellipsis character), but of course this can be changed with the `truncate_builtin_algorithm` configuration setting (see earlier). Example (see the variables used in earlier example):

Template

    ${longName?truncate_m(16)}
    ${difficultName?truncate_w_m(16)}
    ${longName?truncate_c_m(16)}

Output

    This is a <span class='truncateTerminator'>[&#8230;]</span>
    This <span class='truncateTerminator'>[&#8230;]</span>
    This is a to<span class='truncateTerminator'>[&#8230;]</span>

Note above that the terminator string was considered to be only 3 characters long (`'['`, `'…'`, `']'`) by the truncation built-ins, because inside the terminator string they only count the characters outside HTML/XML tags and comments, and they can also interpret numeric character references (but not other entity references). (The same applies when they decide if the terminator starts with dot or ellipsis; preceding tags/comments are skipped, etc.)

If a markup terminator is used (like above), the return value of the `truncate..._m` built-in will be markup as well, which means that auto-escaping won't escape it. Of course, the content of the truncated string itself will be still auto-escaped:

Template

    <#ftl output_format='HTML'>
    ${'This is auto-escaped: <span>'}
    ${'This is auto-escaped: <span>, but not the terminator string'?truncate_m(41)}

Output

    This is auto-escaped: &lt;span&gt;
    This is auto-escaped: &lt;span&gt;, but not <span class='truncateTerminator'>[&#8230;]</span>

## uncap_first

The opposite of `cap_first`. The string with the very first word of the string un-capitalized. Note that this uses locale-aware conversion, that is, the result can be different depending on the current `locale` (language, country).

## upper_case

The upper case version of the string, using rules that depend on the current `locale` (language, country). For example `"KARIŞIK işaretler"?upper_case` will be `"KARIŞIK IŞARETLER"` in most locales, but with Turkish locale it will be `"KARIŞIK İŞARETLER"` (note the dot above the 2nd "I").

To convert to upper case for computer consumption (as opposed to human consumption), use the `c_upper_case` built-in instead!

## url

Note:

This built-in is available since FreeMarker 2.3.1. It doesn't exist in 2.3.

The string after URL escaping. This means that all non-US-ASCII and reserved URL characters will be escaped with `%XX`. For example:

Template

    <#assign x = 'a/b c'>
    ${x?url}

The output will be (assuming that the charset used for the escaping is an US-ASCII compatible charset):

Output

    a%2Fb%20c

Note that it escapes all reserved URL characters (`/`, `=`, `&`, ...etc), so this encoding can be used for encoding query parameter values, for example:

Template

    <a href="foo.cgi?x=${x?url}&y=${y?url}">Click here...</a>

Note:

Above no HTML encoding (`?html`) was needed, because URL escaping escapes all reserved HTML characters anyway. But watch: always quote the attribute value, and always with normal quotation mark (`"`), never with apostrophe quotation mark (`'`), because apostrophe quotation mark is not escaped by the URL escaping.

To do URL escaping a charset must be chosen that will be used for calculating the escaped parts (`%XX`). If you are HTML page author and you don't really understand this, don't worry: the programmers should configure FreeMarker so that it uses the proper charset by default (programmers: see more below...). If you are a more technical minded user, then you may want to know that the charset used is specified by the `url_escaping_charset` setting, that can be set in template execution time (or, preferably, earlier by the programmers). For example:

Template

    <#--
      This will use the charset specified by the programmers
      before the template execution has started.
    -->
    <a href="foo.cgi?x=${x?url}">foo</a>

    <#-- Use UTF-8 charset for URL escaping from now: -->
    <#setting url_escaping_charset="UTF-8">

    <#-- This will surely use UTF-8 charset -->
    <a href="bar.cgi?x=${x?url}">bar</a>

Furthermore, you can explicitly specify a charset for a single URL escaping as the parameter to the built-in:

Template

    <a href="foo.cgi?x=${x?url('ISO-8895-2')}">foo</a>

If the `url` built-in has no parameter, then it will use the charset specified as the value of the `url_escaping_charset` setting. This setting should be set by the software that encloses FreeMarker (e.g. a Web application framework), because it is not set (`null`) by default. If it is not set, then FreeMarker falls back using the value of the `output_encoding` setting, which is also not set by default, so it is again the task of the enclosing software. If the `output_encoding` setting is not set either, then the parameterless `url` built-in can't be executed, and it will cause execution time error. Of course, the `url` built-in with parameter always works.

It's possible to set `url_escaping_charset` in the template with the `setting` directive, but it is bad practice, at least in true MVC applications. The `output_encoding` setting can't be set with the `setting` directive, so that's surely the task of the enclosing software. You may find more information regarding this here...

## url_path

Note:

This built-in is available since FreeMarker 2.3.21.

This is the same as the `url` built-in, except that it doesn't escape slash (`/`) characters. This meant to be used for converting paths (like paths coming from the OS or some content repository) that use slash (not backslash!) to a path the can be inserted into an URL. The most common reason why this conversion is needed is that folder names or file names might contain non-US-ASCII letters ("national" characters).

Note:

Just like with the `url` built-in, the desired URL escaping charset (or as a fall back, the output encoding) must be set in the FreeMarker configuration settings, or else the built-in will give error. Or, you you have to specify the charset like `somePath?url_path('utf-8')`.

## word_list

A sequence that contains all words of the string in the order as they appear in the string. Words are continual character sequences that contain any character but white-space. Example:

Template

    <#assign words = "   a bcd, .   1-2-3"?word_list>
    <#list words as word>[${word}]</#list>

will output:

Output

    [a][bcd,][.][1-2-3]

## wrap

Note:

This built-in is available since FreeMarker 2.3.35.

Word-wraps the string so that if possible, no line is longer than the width given as the 1st parameter. It breaks line at white-space only. A section without white-space that's longer than the width is emitted on its own line without being broken.

White-space treatment:

- Each continuous sequence of white-space characters in the input is in effect collapsed to a single space, or removed if they are before a word-wrapping line-break

- The result always ends with a line-break

- All leading and trailing whitespace of the input (including line-breaks!) is removed in effect

- Non-breaking space (U+00A0) is not treated as white-space by this built-in. (We treat the Java regular expression `\s` as white-space, which does not include the non-breaking space.)

Example:

Template

    ${"Some long text that need to be wrapper at reasonable width"?wrap(25)}

will output this:

Output

    Some long text that need
    to be wrapper at
    reasonable width

The width parameter is truncated to integer, and must be at least 1.

### Adding line suffixed

An optional 2nd parameter is a prefix prepended to the first output line. The optional 3rd parameter is a prefix prepended to all subsequent lines. If the 3rd parameter is omitted, the 2nd parameter is used for all lines.

This is useful for generating wrapped comments, such as documentation blocks. For example:

Template

    <#assign text = "This is a long description that should be wrapped" />
    ${text?wrap(40, " * @brief ", " *         ")}

will output this:

Output

     * @brief This is a long description
     *         that should be wrapped

With a single prefix used for all lines:

Template

    ${"A comment that needs to be wrapped at a reasonable width"?wrap(40, "// ")}

will output this:

Output

    // A comment that needs to be wrapped at
    // a reasonable width

## xhtml (deprecated)

Note:

This built-in is deprecated by the auto-escaping mechanism introduced in 2.3.24. To prevent double escaping and confusion in general, using this built-in on places where auto-escaping is active is a parse-time error. To help migration, this built-in silently bypasses HTML markup output values without changing them.

The string as XHTML text. That is, the string with all:

- `<` replaced with `&lt;`
- `>` replaced with `&gt;`
- `&` replaced with `&amp;`
- `"` replaced with `&quot;`
- `'` replaced with `&#39;`

The only difference between this built-in and the `xml` built-in is that the `xhtml` built-in escapes `'` as `&#39;` instead of as `&apos;`, because some older browsers don't know `&apos;`.

Warning!

When inserting the value of an attribute, always quote it, or else it can be exploited by attacker! This is WRONG: `<input name="user" value=${user?xhtml}/>`. These are good: `<input name="user" value="${user?xhtml}"/>`, `<input name="user" value='${user?xhtml}'/>`.

## xml (deprecated)

Note:

This built-in is deprecated by the auto-escaping mechanism introduced in 2.3.24. To prevent double escaping and confusion in general, using this built-in on places where auto-escaping is active is a parse-time error. To help migration, this built-in silently bypasses XML and HTML markup output values without changing them.

The string as XML text. That is, the string with all:

- `<` replaced with `&lt;`
- `>` replaced with `&gt;`
- `&` replaced with `&amp;`
- `"` replaced with `&quot;`
- `'` replaced with `&apos;`

Warning!

When inserting the value of an attribute, always quote it, or else it can be exploited by attackers! This is WRONG: `<input name="user" value=${user?xml}/>`. These are good: `<input name="user" value="${user?xml}"/>`, `<input name="user" value='${user?xml}'/>`.

## Common flags

Many string built-ins accept an optional string parameter, the so called "flags". In this string, each letter influences a certain aspect of the behavior of the built-in. For example, letter `i` means that the built-in should not differentiate the lower and upper-case variation of the same letter. The order of the letters in the flags string is not significant.

This is the complete list of letters (flags):

- `i`: Case insensitive: do not differentiate the lower and upper-case variation of the same letter.

- `f`: First only. That is, replace/find/etc. only the first occurrence of something.

- `r`: The substring to find is a regular expression. FreeMarker uses the variation of regular expressions described at http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html (note that the presence of some pattern features depends on the Java version used).

- `m`: Multi-line mode for regular expressions. In multi-line mode the expressions `^` and `$` match just after or just before, respectively, a line terminator or the end of the string. By default these expressions only match at the beginning and the end of the entire string. Note that `^` and `$` doesn't match the line-break character itself.

- `s`: Enables dot-all mode for regular expressions (same as Perl singe-line mode). In dot-all mode, the expression `.` matches any character, including a line terminator. By default this expression does not match line terminators.

- `c`: Permits whitespace and comments in regular expressions.

Example:

Template

    <#assign s = 'foo bAr baar'>
    ${s?replace('ba', 'XY')}
    i: ${s?replace('ba', 'XY', 'i')}
    if: ${s?replace('ba', 'XY', 'if')}
    r: ${s?replace('ba*', 'XY', 'r')}
    ri: ${s?replace('ba*', 'XY', 'ri')}
    rif: ${s?replace('ba*', 'XY', 'rif')}

This outputs this:

Output

    foo bAr XYar
    i: foo XYr XYar
    if: foo XYr baar
    r: foo XYAr XYr
    ri: foo XYr XYr
    rif: foo XYr baar

This is the table of built-ins that use these common flags, and which supports which flags:

Built-in | `i` (ignore case) | `r` (reg. exp.) | `m` (multi-line mode) | `s` (dot-all mode) | `c` (whitesp. and comments) | `f` (first only)
--- | --- | --- | --- | --- | --- | ---
`replace` | Yes | Yes | Only with `r` | Only with `r` | Only with `r` | Yes
`split` | Yes | Yes | Only with `r` | Only with `r` | Only with `r` | No
`matches` | Yes | Ignored | Yes | Yes | Yes | No
`keep_after` | Yes | Yes | Yes | Yes | Yes | Ignored
`keep_after_last` | Yes | Yes | Yes | Yes | Yes | Ignored
`keep_before` | Yes | Yes | Yes | Yes | Yes | Ignored
`keep_before_last` | Yes | Yes | Yes | Yes | Yes | Ignored
`ensure_starts_with` | Yes | Ignored | Yes | Yes | Yes | Ignored

Previous Next