Literals, Operators & Preprocessing

A Standard Expression is evaluated by Thymeleaf’s own parser. Only the part between ${ and } is handed to OGNL (or Spring EL in a Spring application). That is why the same operator can be written in two places with the same visible result but different engines:

The first form follows Thymeleaf’s rules (null handling, comparison of numbers of different types, the textual aliases below). The second follows the rules of the expression language, which for example has its own Elvis (?:), safe navigation (?.) and collection projection syntax. Both are valid; choose one style per project and remember the difference when an expression behaves differently from what you expect. The sections below use the operators outside the braces unless stated otherwise, because that is the portable, documented Standard Expression syntax.

Source: Using Thymeleaf — 4.6 Boolean literals

The running data of this page is a small Edition record, the book the Bookshelf shows on a detail page, and a controller that puts two of them in the model: edition (Dune, three copies in stock, no subtitle, no rating) and sold (Emma, sold out, empty subtitle, rating 5):

Source: Spring Boot — Servlet Web Applications

A literal is a fixed value written directly in the expression. Thymeleaf has four kinds, plus a looser notation called a literal token.

The first th:if printed nothing because edition.available is true; the second rendered its div (<div>no subtitle</div>, left out of the listing above) because edition.subtitle is null. Notice the prototype text inside each element (a catalogue, 0) was replaced; that text is only there so the file reads well when opened in a browser (natural templating).

Source: Using Thymeleaf — 4.6 Text literals, Number literals, Boolean literals, The null literal

Any text-like expressions, whether literals, variables or messages, are appended with the plus operator, +. It is also the arithmetic addition, so the type of the operands decides which one is applied: if either side is text, the result is a string.

The last line is the classic surprise: once the left side is text, every following plus sign appends, so 412 and 3 become 4123. Parenthesise the arithmetic.

Source: Using Thymeleaf — 4.7 Appending texts

Thymeleaf offers +, -, *, / and %, with the textual aliases div for / and mod for %. A leading minus negates, and parentheses group. Numeric operands keep their precision (BigDecimal stays BigDecimal).

The first ten paragraphs render 9, 3.5, 3.5, 1, 1, 25.00, 37.50, -3, 8 and 824, and the list renders alternating odd and even classes:

The aliases div and mod read as words where / and % would be symbols inside an attribute value. The parentheses around ${n} % 2 == 1 in th:with make the whole comparison the value assigned to odd; keep grouping explicit. As with ==, the same arithmetic is also available inside the braces, where OGNL or Spring EL runs it (${edition.pages * 2}); only the form outside the braces is evaluated by Thymeleaf itself.

Source: Using Thymeleaf — 4.9 Arithmetic operations

Values are compared with >, <, >= and <=, and equality is tested with == and !=. In an XML/HTML attribute the symbols < and > should not appear raw, so write < and >, or use the textual aliases:

The boolean operators are and, or and !/not. Use parentheses to group, and note that not applies to the expression that follows it:

Every th:if above rendered (with admin set to true in the model). The > form and the alias are equivalent; the aliases are easier to read in a template that is also opened as a design prototype. th:if and th:unless and the truthiness rules for values that are not booleans are the subject of the Iteration & Conditionals page.

Source: Using Thymeleaf — 4.10 Comparators and Equality

A conditional expression picks one of two expressions according to a third: condition ? then : else. Each of the three parts is a Standard Expression, so it can be a variable, a message, a link or a literal. It can be nested with parentheses, and the else part can be omitted, in which case a false condition yields null.

When the condition is false and there is no else, the result is null, and th:class with a null value removes the attribute (the fourth paragraph has no class at all). Wrap the conditional in parentheses when it is an operand of +, as in the fifth paragraph: the question mark binds loosely.

Source: Using Thymeleaf — 4.11 Conditional expressions

The Elvis operator ?: is a conditional without a then part: use the first expression unless it is null, otherwise the second.

Two details are visible in the output. Thymeleaf’s own ?: (outside the braces) tests only for null: an empty string is a value, so the second paragraph prints an empty string, and the fifth (an empty subtitle again) never reaches its fallback. Spring EL’s ?: inside the braces (third paragraph) treats both null and the empty string as missing. Use the form outside the braces when only null should trigger the default, and nested parentheses when the default is itself a conditional, as the fifth paragraph shows.

Source: Using Thymeleaf — 4.12 Default expressions (Elvis operator)

The no-operation token is the underscore, _. As the result of an expression, it means "do nothing", as if the processing attribute were not there at all, so the prototype content of the element stays. This lets a template carry real placeholder text as its default instead of repeating it in a literal:

Compare the second paragraph with ${edition.rating} ?: 'no rating', which would hold the same words twice (once in the attribute and once as prototype text). The fallback of the no-op token fires on null only, like the Elvis operator: ${sold.subtitle} ?: _ with the empty subtitle renders an empty p, not the prototype text. In the third paragraph, the else part is the token, so the attribute keeps the class already written in the file. The same token is used in fragment expressions (th:insert="${cond} ? ~{x} : _") on the Fragments page.

Source: Using Thymeleaf — 4.13 The No-Operation token

Writing ${edition.publishedOn} prints the value with toString(); writing ${{edition.publishedOn}} (and *{{publishedOn}} inside a th:object) hands the value to the conversion service and asks it for a String, which is how dates, numbers and your own types get their display format. What happens depends on who provides that service:

The Spring Boot run on the Bookshelf (Locale en for the first column, es for the second):

Two things come from the Spring side. Without any configuration, Spring formats a LocalDate in the locale’s short style (month first in English, day first in Spanish). Adding one Formatter bean teaches the engine how to print Isbn; Spring Boot registers every Formatter and Converter bean in the MVC conversion service on its own:

Source: Spring Framework — Spring Field Formatting, Thymeleaf + Spring — 9 The Conversion Service

To change the default date style for the whole application, set the Boot property instead of writing a formatter:

With that property, the second and sixth paragraphs above both render 1965-08-01 and Published 1965-08-01, and spring.mvc.format.date-time and spring.mvc.format.time do the same for LocalDateTime and LocalTime. For a one-off pattern, #temporals.format(edition.publishedOn, 'dd MMM yyyy') (Expression Utility Objects page) prints 01 Aug 1965 (01 ago 1965 in Spanish) and ignores the conversion service.

Source: Spring Boot — Common Application Properties

Outside Spring, register your own conversion service by extending AbstractStandardConversionService and installing it in the StandardDialect. Override convertToString for the string conversions (the convertOther hook handles targets other than String):

The template <p th:text="${d}">x</p><p th:text="${{d}}">x</p> for 1965-08-01 renders <p>1965-08-01</p><p>01/08/1965</p>: the single braces still print toString(), only the double braces go through the conversion service. The Standalone Engine & Configuration page covers how the engine and its dialects are assembled.

Source: Javadoc: AbstractStandardConversionService, Using Thymeleaf — 4.14 Data Conversion / Formatting

Preprocessing is a second evaluation pass that runs before the normal one. Any part of an expression written between double underscores, __...__, is evaluated first, and its result is pasted into the expression text; the engine then evaluates the rewritten expression. The preprocessed part is an ordinary expression (usually a variable, selection or message expression), so the feature lets data decide which expression is run: a property name, a message key, a form field name.

With prop set to title, columns to the list title, pages and the message files below:

the output (Spanish locale for the last paragraph) is:

The first line is preprocessed into ${edition.title} and then evaluated; inside the loop the preprocessing runs again for every col, yielding ${edition.title} and ${edition.pages}; the message key status.__${edition.status}__ becomes status.NEW, a lookup in the localized bundle. Typical uses are exactly these: a configurable list of columns, enum-driven message keys and reusable form-field fragments (th:field="*{__${field}__}", shown on the Reusable UI Components page).

Source: Using Thymeleaf — 4.15 Preprocessing

Because these rules are easy to get subtly wrong (the Total: 4123 case, the empty-string Elvis case), pin the interesting ones with a MockMvc test. With spring-boot-starter-thymeleaf-test and the web MVC test starter on the classpath (Boot 4 package org.springframework.boot.webmvc.test.autoconfigure):

Both tests passed in the scratch application. The @WithMockUser is needed only because the Bookshelf is secured.

Source: Spring Boot — Testing Spring Boot Applications

The expression syntax of this page is the one documented in the 3.1 tutorial. What deserves attention on a current version is Appendix D: templates that call static methods or beans from th:utext, th:on*, URL bases or preprocessing fail with a TemplateProcessingException, and the documented fix is to compute the value in the controller. With Spring Framework 7 the thymeleaf-spring6 module is still the one in use (no thymeleaf-spring7 exists). The consulted book Taming Thymeleaf (Leanpub, consulted PDF v1.1.1 from 2021) covers literal substitution and preprocessing, and its explanations of the operators still apply; examples from that generation that put T(...), beans or request parameters into preprocessing or th:utext need the restructuring described above.