Functions

The list of functions available with Jtwig Core.

abs

Mathematical function allowing to get the absolute value of an expression. For example, {{ abs(-1) }} will 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 capitalizing the first word.

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

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.

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.

  1. The number to be formatted
  2. The number of fractional digits (optional)
  3. The decimal separator (optional)
  4. 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 opposite 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('jtwig', ''}}

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