Iteration & Conditionals

The examples render a small in-memory catalogue so that every output can be reproduced without a database. A Title is a plain class with getters (the Bookshelf’s persistent entities would work the same way), and CatalogueData builds four titles and three genres, one of which is empty.

Source: Using Thymeleaf — Iteration basics

A page that lists things needs a way to say "repeat this piece of markup once per element". Thymeleaf keeps the template natural by letting you write one exemplar row, as a designer would mock it up, and attach th:each to it. The attribute value has the shape iterVar : ${iteratedExpression}, read as "for each element in the result of the iterated expression, repeat this element, binding the current element to the iteration variable". The iteration variable is scoped to the element that carries th:each and everything inside it, so the <td> cells see it but a sibling element does not.

The attribute is processed by the Standard Dialect’s th:each attribute processor at template processing time (not at parse time). It repeats the host element together with its body, so on a table you put it on the <tr>, on a list on the <li>. th:each has a higher precedence than th:if, which matters when both are on one element (see Attribute precedence below). It is not one of the attributes evaluated in the restricted expression mode: the iterated expression runs in the general mode, where only the general restrictions apply (static access to most JDK, Spring and Thymeleaf infrastructure classes is refused). The template stays valid HTML and viewable in a browser, because the other rows are simply absent from the prototype.

Controller side, the Bookshelf controller only puts the data in the model; the template does the repetition.

A first, minimal template repeats a list row:

Source: Using Thymeleaf — Using th:each

Rendered (one <tr> per title, and the prototype row has disappeared into the repetition):

If the iterated expression evaluates to null, the loop simply runs zero times; no exception is raised and the element is not output. A different th:each on a <th:block> repeats several sibling elements without adding a wrapper (the synthetic block element is described on the local variables page of this section), for instance a definition list:

Source: Using Thymeleaf — Iteration basics

Rendered: <dt>Dune</dt><dd>Frank Herbert</dd><dt>Neuromancer</dt><dd>William Gibson</dd> and so on, with no th:block left in the output.

th:each is not limited to java.util.List. The tutorial lists the supported kinds, and the table adds what the iteration variable holds and what was observed on 3.1.5 when the status variable is used with each kind (see The iteration status variable).

The next template iterates one of each kind. The model variables are set as follows (a standalone-style Context, the same names a controller would put in a Model):

Source: Using Thymeleaf — Iterable values

Each line rendered on its own (the null line renders nothing):

A numeric loop (a rating of stars, page buttons) has no dedicated attribute: iterate the list returned by the #numbers.sequence(from, to) utility object, which is described with the other expression utility objects in this section.

Two cautions come from the streaming kinds. A Stream variable that is read by two th:each attributes fails on the second one, because the stream was already consumed; the failure reaches you as a TemplateInputException whose root cause is java.lang.IllegalStateException: stream has already been operated upon or closed. Put a Stream in the model only when exactly one loop reads it, or collect it to a List in the controller. Because an Iterator, Enumeration or Stream can be read only once and has no size, a List is the safer default for a model attribute.

Many layouts need more than the element: a row number, a separator between items but not after the last, a zebra stripe. th:each offers a status variable for this. It is declared by adding a second name after the iteration variable, separated by a comma: th:each="title, stat : ${titles}". The status object has these properties:

If you do not name a status variable, Thymeleaf creates one for you named after the iteration variable with the suffix Stat, so th:each="title : ${titles}" makes titleStat available. The status variable has the same scope as the iteration variable. The following template prints every property and the implicit variable for the Bookshelf titles:

Source: Using Thymeleaf — Keeping iteration status

Rendered (index, count, size, current name, even, odd, first, last):

The most useful last pattern is a separator that is not printed after the final element. The tags of a title are joined with commas without a trailing comma by testing last of an inner loop:

Source: Using Thymeleaf — Keeping iteration status

For the tags of Dune this renders <span>classic, </span><span>space</span>.

A zebra stripe is the classic use of the status variable: give odd rows a CSS class. There are two idiomatic forms. The first sets the whole class attribute only for odd rows (an expression that yields null removes the attribute), which is the form in the tutorial:

Rendered: <tr class="odd"><td>Dune</td></tr><tr><td>Neuromancer</td></tr><tr class="odd"><td>Solaris</td></tr><tr><td>Hyperion</td></tr>, so even rows carry no class attribute at all. The second keeps the static classes of the prototype and appends one of two classes, which is what you want when the row already has a class such as row:

Source: Using Thymeleaf — Keeping iteration status

Rendered: <tr class="row odd"> for Dune and Solaris and <tr class="row even"> for Neuromancer and Hyperion. The th:class, th:classappend and related attributes are described on the attribute-setting page of this section. When the stripe is purely decorative, CSS does it with no template logic (tbody tr:nth-child(odd)), which is the better choice for a static table. Use the status variable when the class must be computed, or when the same list is rendered in a context without your stylesheet.

A page often reads a large collection only under a condition: a "show details" flag, an authorisation check, a collapsed panel. Loading the collection in the controller costs a query even when the page ends up not using it. Thymeleaf offers lazily resolved context variables for this. A variable that implements org.thymeleaf.context.ILazyContextVariable, usually by extending the default implementation org.thymeleaf.context.LazyContextVariable<T> and implementing loadValue(), is resolved only at the moment an expression reads it. Templates use it exactly like an ordinary variable and need no knowledge of its laziness.

In Spring MVC the lazy variable is simply a model attribute:

Source: Using Thymeleaf — Optimizing through lazy retrieval of data

With /lazy (flag false) the list is not rendered and loadValue() is never called; with /lazy?showTitles=true the <ul> contains the four titles and loadValue() ran once. A test can assert both facts through the counter:

Source: Spring Boot reference — Auto-configured Spring MVC tests

Two properties of the implementation are worth knowing. The value is memoized per variable instance: when the same lazy variable is read by two expressions in one rendering (two copies of the list above in a standalone test) loadValue() still ran once. And the laziness only covers the loading; it does not make iteration streaming. Once the variable is read, the whole returned value exists in memory. Keep loadValue() free of side effects and do not close over a request-scoped resource that may be gone by the time the view renders (with Spring Boot, remember that spring.jpa.open-in-view decides whether lazy JPA associations can still be loaded while the view renders).

th:if renders the element, with its body, only when its expression is true; th:unless is the inverse and renders it only when the expression is false. Both are processed at template processing time, and when the condition is not met the element is simply not output (it is not hidden with CSS). They evaluate their value in the general expression mode, which is why you can write ordinary boolean expressions with and, or, not, the comparison operators and the utility objects. Their value does not have to be a boolean.

When one value selects among several outputs, a chain of th:if is noisy. th:switch sets the value on a container element and th:case marks the alternatives inside it:

Source: Using Thymeleaf — Switch statements

For Dune, Neuromancer and Hyperion this renders <span>Available</span>, <span>On loan</span> and <span>Unavailable</span>. The rules, all verified:

Source: Using Thymeleaf — Switch statements

The T() form is a convenience for the examples. In a real application a status label is better looked up in a message bundle, as the next section shows, and the th:switch is reserved for markup that really differs between values.

The full Bookshelf catalogue template puts the pieces together. It renders a table only when there are titles, stripes the rows with the status variable, switches the status label, joins the tags with the last property of a nested loop and shows an "untagged" marker when a title has none. When the list is empty, a plain paragraph replaces the whole table, so the page never shows a headline with empty column headers.

Source: Using Thymeleaf — Some more pages for our grocery

GET /catalogue renders (white space condensed; the first and third rows are odd, the second and fourth even):

GET /catalogue?empty=true renders only <h1>Catalogue</h1> followed by <p>The catalogue is empty.</p>: the th:unless removed the table and the th:if kept the message. A test for the three behaviours uses MockMvc:

Source: Spring Boot reference — Auto-configured Spring MVC tests

Three empty-state patterns are worth distinguishing:

Data that has a parent and children, such as genres that contain titles, needs one th:each inside another. Each loop has its own iteration and status variable; use distinct names, and the inner loop can read the outer variable.

Source: Using Thymeleaf — Iteration basics

Rendered (the empty genre falls through to the message):

Each loop numbers independently, and the two status variables can be combined: ${genreStat.index} + ':' + ${titleStat.index} yields 0:0 and 0:1 in the first genre and 1:0 in the second. An iteration variable shadows a model or local variable of the same name for the duration of the loop and the outer value is visible again after it: a th:with="t='outer'" paragraph containing a th:each="t : ${titles}" loop printed the title names inside the loop and outer after it. When an inner and outer variable need to coexist, give them different names rather than relying on shadowing.

The order of evaluation inside a nested structure is outer first. The outer element’s th:each runs before the inner element’s attributes, so the inner loop and any th:if on it see the current outer element, and a condition on the outer element can drop the inner loop altogether, as the lazy-loading example does.

When several th:* attributes sit on the same element Thymeleaf applies them in a fixed order, not the order they are written. In the tutorial’s precedence table, fragment iteration (th:each) comes before conditional evaluation (th:if, th:unless, th:switch, th:case), so the condition is evaluated once per iteration and can read the iteration variable. A filter on the same element works as expected:

Source: Using Thymeleaf — Attribute precedence

Rendered: <li>Dune</li><li>Solaris</li> (the two titles with copies). The complete precedence table, with every attribute, is on the local variables, precedence, comments and blocks page of this section. Two practical choices follow. Filtering in the template is acceptable for a short list, but for a large one it iterates every element only to discard most of them, so filter in the controller or the service (or in the query) instead. When you do want a template-side filter without a condition per element, a SpEL collection selection is a compact alternative: th:each="title : ${titles.?[copies > 0]}" rendered the same two titles, and a projection ${titles.![name]} iterates just the names. Collection selection and projection are Spring EL features; in a standalone engine that uses OGNL the equivalent syntax differs.

The Thymeleaf + Spring tutorial builds its first screen as a listing and combines th:unless, th:each, nested loops, a status variable and the message bundle. The same techniques apply to the Bookshelf. The wrapping th:unless="${#lists.isEmpty(...)}" is the empty-state pattern above; a nested loop reads th:each="row, rowStat : ${sb.rows}" with ${rowStat.count} as the row number, exactly like the genre example.

Two Spring-specific details belong to that listing. First, an enum is translated through the message bundle with a literal-substitution key built from the value: th:text="#{|status.${title.status}|}", with the keys status.AVAILABLE, status.ON_LOAN and status.LOST in messages.properties, which is the better way to label a status than a th:switch because the texts become translatable. Second, the double-brace form ${{value}} applies the Spring conversion service to a value (dates, numbers, your own types) at output time; it is the subject of the conversion and formatting page of this section.

Source: Thymeleaf + Spring — Listing Seed Starter Data

With a messages_es.properties containing status.AVAILABLE=Disponible, status.ON_LOAN=Prestado and status.LOST=Perdido, a request with Accept-Language: es rendered <span>Disponible</span>, <span>Prestado</span>, <span>Disponible</span> and <span>Perdido</span> after the titles Dune, Neuromancer, Solaris and Hyperion. (Spring Boot falls back to the JVM’s default locale when no bundle matches the requested language, so check what spring.messages.fallback-to-system-locale does on your machine when a test unexpectedly returns another language.)

A natural template should look right when opened directly in a browser. A th:each row shows only one prototype row, which is usually enough, but a designer may want to see a realistic table with several rows. Add extra mock rows with th:remove="all" so that the engine deletes them while the browser still shows them (the attribute is covered with the other removal options on the fragments page of this section):

Source: Using Thymeleaf — Removing template fragments

Rendered: <table><tr><td>Dune</td></tr><tr><td>Neuromancer</td></tr><tr><td>Solaris</td></tr><tr><td>Hyperion</td></tr></table>, with the mock row gone.