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 ${...}).

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.

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

The output:

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

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

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

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.

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.

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!

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!

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

The output:

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.

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:

This will output:

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.

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:

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.

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.

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/".

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.

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:

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

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.

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

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:

When inserting the value of an attribute, always quote it, or else it can be exploited by attackers! This is WRONG: . This is good: .

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.

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.

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:

will output:

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.

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:

, and this is good:

.

Example:

will output:

The exact escaping rules are:

" is escaped as \"

' is escaped as \'

\ is escaped as \\

/ is escaped as \/ if the / is directly after