Built-in Functions

`abs`

Mathematical function allowing to get the absolute value of an expression. For example, {{ abs(-1) }} would produce 1. It is expecting only one argument which must be converted to a number. Such conversion uses the NumberConverter configured. For more details check the Environment documentation.

`batch`

The batch function splits a given list in equally sized groups of items. It expects two or three arguments. A list as first argument, note that a list in Jtwig is a configurable concept as mentioned previously, whereby the ``CollectionConverter`` defined in the configuration will be used, it depends on the converter defined in the environment. The second argument is the group size. There is also an optional third argument used as padding, that is, if the last group is incomplete, the third argument will be used to fill it.

{{ batch([1,2,3], 2) }}

The previous example will output [[1, 2], [3]].

{{ batch([1,2,3], 2, 0) }}

The previous example, now with the padding argument, will output [[1, 2], [3, 0]].

`block`

Block function can be used to output the content of a defined block tag (check {% block %} tag definition).

{% block one %}Hello{% block %}{{ block('one') }}

The previous example will print HelloHello.

`capitalize`

The capitalize function is expecting one argument. It converts that argument to a String, using the StringConverter (check Environment documentation for more information).

{{ capitalize('hello world') }}

The previous template will render as Hello world which is the result of capilatizing the first word.

`concat` or `concatenate`

This function allows one to concatenate a set of strings. It is expecting an arbitrary number of arguments (varargs).

{{ concat('1', '+', '1', '=', '2') }}

Under the wood it uses the defined ``StringConverter`` to convert individual objects to a string representation and then concatenating them. The previous example will output ``1+1=2``.

`constant`

The constant function comes with two possible outputs depending on the number of arguments supplied. If one argument is supplied, it will return the value of the constant. If two arguments are provided, then it will compare the constant value against the second argument.

{{ constant("org.jtwig.example.TestClass.CONSTANT_NAME") }}

As shown in the above example, the expression will print the result of evaluating (using reflection) the constant with name CONSTANT_NAME defined in class org.jtwig.example.TestClass. Note that the evaluation will only work if the constant is public.

{{ constant("org.jtwig.example.TestClass.CONSTANT_NAME", "value") }}

The above example will return a Boolean expression. It will be true if the constant value is equal to "value".

`default`

The default function is expecting two arguments. It returns the second argument if the first argument is either null or Undefined.

{{ default(null, 'Hello') }} {{ default(undefinedVariable, 'World') }}

if variable undefinedVariable is not defined in the provided JtwigModel then the previous example will produce Hello World.

`defined`

The defined function is useful to check if a given expression is defined or not. This logic is tied to the definition of an Undefined expression, explained later on (Jtwig core engine). It returns true if the given expression is defined, false otherwise.

{% if (defined([1, 2][5])) %}KO{% else %}OK{% endif %}

The previous example will output OK because index 5 of list [1, 2] is undefined.

`empty`

The empty function returns a boolean value. As input it is expecting a generic object, it returns true if the given input falls in one of the following scenarios:

null
Undefined
non-empty list (implementing Iterable interface) of items
non-empty array
non-empty map
non-zero number

Note that under the wood this function is using NumberConverter and CollectionConveter. Check the example below.

{% if (empty([1, 2])) %}A{% else %}B{% endif %}

The previous example produces B.

`escape`

The escape function allows to set the escape mode of the current context. A escape mode can be provided in order to choose which escaping strategy to use. If false is provided, it will set the escape mode to none.

escape(<Value> [, <Escape Mode>])

By default it uses HTML escape mode, meaning HTML special characters will be then escaped. For more information about available escaping strategies check Environment chapter.

{% autoescape 'html' %}
& {{ '&' | escape(false) }}
{%.endautoescape %}

The previous example, based on the Jtwig implementation of its processing pipeline and the escape mode functionality will produce &&.

`even`

This function is quite simple, it is expecting one number as argument and it returns true when that number is even, false otherwise.

{% if (even(2)) %}A{% else %}B{% endif %}

The previous example prints A. Note that the even function uses the NumberConverter concept to try to conver the given input to a number. If this conversion fails an exception will be thrown.

`first`

The first function returns the first element of a collection or String. If the argument provided is not a collection or a String, it will just return the input argument.

{{ first([1, 2]) }}

If the given argument is an empty list or String, then it returns Undefined. Note that this function uses the CollectionConverter mechanism. The previous template will output 1.

`format`

The format function is just a Jtwig wrapper to call the String.format method available in Java. It receives an arbitrary number of arguments where the first is the template parameter (converted to a String) and the remaining arguments is provided as the model values for the String.format method.

{{ format('hello %s', 'world') }}

The previous example will print hello world. Note that this function uses the StringConverter (check Environment documentation for more information).

`iterable`

The iterable function allows one to check if a given argument is a collection for loops can iterate over, or index/map selections can be used.

{% if (iterable(2)) %}A{% else %}B{% endif %}

Iterable uses under the wood the CollectionConverter, which whenever an object can be converted to a Jtwig collection it will be iterable. The previous template will render B because 2 is not iterable as per default configuration.

`join`

The join function provides functionality somehow similar to the concat function, however they have some differences. To start with, join takes only one or two arguments, where the first argument is expected to be a list and the second, optional, argument a string to be used as the separator.

{{ join([1, null, 2], ', ') }}

The previous example will print 1, 2. Note that, join function ignores null values.

`keys`

Keys function can be used to expose the collection of keys for a given collection. It uses the configured CollectionConverter (for more details check the Environment documentation).

{{ keys(['A', 'B']) }}

The previous example, as per the default configuration, will print [1, 2].

`last`

The last function returns the last element of a collection or String. If the argument provided is not a collection or a String, it will just return the input argument.

{{ last([1, 2]) }}

If the given argument is an empty list or String, then it returns Undefined. Note that this function uses the CollectionConverter mechanism (check Environment documentation for more information). The previous template will output 2.

`length`

The length function returns the length of a given collection or String. If neither a collection or String is provided then it returns 0 for both null and Undefined, otherwise 1 will be the result.

{{ length([1, 2]) }}

{{ length(null) }}

{{ length(9) }}

The previous examples will print respectively 2, 0 and 1. Note that this function uses the defined CollectionConverter configured, for more information visit the Environment documentation.

`lower`

Lowers the case of the String provided. Note that this function uses the StringConverter (check Environment documentation for more information). The following example will produce jtwig.

{{ lower('JTWIG') }}

`merge`

The merge function allows one to merge an arbitrary number of lists together by the given order. This function requires at least two arguments to run. It also supports singular elements as arguments.

{{ merge(1, 2, 3) }}

{{ merge([1, 2], 3) }}

The previous two examples return the same output, which is, [1, 2, 3]. Note that, this function uses the CollectionConverter defined by the Jtwig configuration.

`nl2br`

This function allows one to convert new line characters into it's HTML sibling <br />, just as simple as that. It uses StringConverter (check Environment documentation for more information) to convert the given argument to a String.

`number_format`

The number_format allows one to format a given number with specific symbols for the grouping and decimal separators, also the number of fractional digits. This function expects at least one argument and can receive up to four arguments. The list of arguments is presented below by the order they are expected by Jtwig.

The number to be formatted
The number of fractional digits (optional)
The decimal separator (optional)
The grouping separator (optional)

{{ number_format(11000.136, 2, '.', ' ') }}

The previous example will produce 11 000.14. The rounding applied in here is the same strategy as BigDecimal.ROUND_HALF_DOWN (check Java documentation for more information). This function uses StringConverter to convert the third and fourth arguments to Strings, it also uses the NumberConverter to convert the first and second arguments to numbers, check Environment documentation for more information about this converters.

`odd`

This is the oposite of the even function, it is expecting one number as argument and it returns true when that number is odd, false otherwise.

{% if (odd(2)) %}A{% else %}B{% endif %}

The previous example prints B. Note that the even function uses the NumberConverter concept to try to conver the given input to a number. If this conversion fails an exception will be thrown.

`raw`

This function clears the current escape mode of the context. It is equivalent to escape(false). This function does not take arguments.

{% autoescape 'HTML' %}
{{ '&' | raw }}
{% endautoescape %}

The previous example will produce & as output.

`replace`

The replace function allows one to specify a String and a map of replacements replacing all the ocurrences of the keys in the provided map by their respective value converted to a String. It expects two arguments, where it uses StringConverter to convert the first argument to a String and CollectionConverter to convert the second argument to a list of key value pairs.

{{ replace('Hello %name%', { '%name%': 'world' }) }}

The previous example will produce Hello world as output.

`reverse`

Reverse function reverses the order of the elements in a given collection or String. If no collection neither String is provided then it returns the given argument.

{{ reverse([1, 2]) }}

The previous example will print [2, 1]. Note that this function uses the defined CollectionConverter configured, for more information visit the Environment documentation.

`round`

The round function allows one to round a given number to integer. An optional strategy can be specified as second argument:

'CEIL'
'FLOOR'

{{ round(1.3, 'CEIL') }}

The previous example will produce 2. Note that the strategy selection is case insensitive, so one can either specify 'CEIL' or 'ceil'. If the second argument is not specified BigDecimal.ROUND_HALF_DOWN will be applied. For further information check the official Java documentation.

`slice`

This function is expecting three arguments, where the first argument can either be a String or a collection (it uses CollectionConverter under the wood), and an integer as second and third arguments.

{{ slice("123", 1, 1) }}

{{ slice([1, 2, 3], 0, 2) }}

The second argument is the index position the slice will start from (inclusive), where the third argument is the length of the slice. As shown in the previous two examples, the result will be "2" and [1, 2] respectively. Note that, slice is smart enough to handle boudary cases, for exaple:

{{ slice("123", 2, 3) }}

{{ slice("123", 5, 1) }}

The previous examples will still return a slice, depending on the number of characters or items provided in the first argument, the previous examples would then resolve the slice to "3" and ""

`sort`

Sort can be used to sort elements of a given collection in ascending order. It is based on the underlying core Java java.lang.Comparable interface, which elements should implement.

{{ sort([1, 3, 2]) }}

The previous example will produce [1, 2, 3].

`split`

This function expects two arguments, using the second argument provided to split the first one into a collection. Such arguments are converted to String using the StringConverter configured in the Environment as detailed previously.

{{ split('jtwig-2', '-') }}

The previous example will return [jtwig, 2].

`striptags`

The striptags function is expecting at least one argument or two at most. This function emulates the PHP strip_tags function behaviour in Java. The first argument is the String which HTML elements will be stripped. Where the second optional argument (a String aswell) enables users to specify a list of allowed tags (tags that won't be stripped).

{{ striptags('<a>jtwig</a><button>Submit</button>', '<a>') }}

The previous example will produce <a>jtwig</a>Submit. Note that this function uses StringConverter to convert the arguments to a String, check Environment documentation for further information.

`title`

The title function is expecting one String argument, capitalizing the first letter of all words present in it.

{{ title('hello world') }}

The previous example will produce Hello World. Note that this function uses StringConverter to convert the arguments to a String, check Environment documentation for further information.

`trim`

Similar to the Java sibling String::trim, the trim function in Jtwig removes any whitespace characters from the beggining and/or ending of the given argument.

{{ trim('  Hello World  ') }}

The previous example will produce Hello World. Note that this function uses StringConverter to convert the arguments to a String, check Environment documentation for further information.

`upper`

Changes the case of the String provided by turning all into capitals. Note that this function uses the StringConverter (check Environment documentation for more information). The following example will produce JTWIG.

{{ upper('jtwig') }}

`url_encode`

Encoding values to a url is the role of this function. It is expecting either a String or a map.

{{ url_encode({id: 1, special: '&'}) }}

The previous example produces id=1&special=%26.

{{ url_encode('one&two') }}

The previous example produces one%26two.

Built-in Functions

abs

batch

block

capitalize

concat or concatenate

constant

default

defined

empty

escape

even

first

format

iterable

join

keys

last

length

lower

merge

nl2br

number_format

odd

raw

replace

reverse

round

slice

sort

split

striptags

title

trim

upper

url_encode