Natural Templates & Decoupled Logic

A template is natural when the file is still a valid, displayable prototype after the logic has been added. Thymeleaf achieves this because most Standard Dialect processors are attribute processors: a browser ignores attributes it does not know, so it simply shows the markup and the prototype text, and the engine replaces the prototype values when it runs. Compare the two halves of this rule:

Designing for this has a handful of habits. The list below collects them; each one is demonstrated by the example that follows.

The template below is the Bookshelf list written that way. It uses mock rows removed with th:remove, a prototype-only comment block around a th:block, a parser-level comment, and the dual-path stylesheet and links that the following sections explain one by one.

Opened directly from disk, this file shows a heading, a three-row table (Dune, Neuromancer, Hyperion), the "No books yet." line and the "Several books" line, styled by the relative stylesheet: a perfectly good prototype for a designer. Rendered by the server for two books the output is the following. The mock rows, the designer’s comment, the th:* attributes and the "No books yet." paragraph are gone:

With an empty shelf the iterated row produces nothing, the table body is empty, and the "No books yet." paragraph is kept because its th:remove expression evaluates to none. The controller that feeds the template is an ordinary Spring MVC controller; nothing in it knows the template is natural:

Source: Thymeleaf + Spring — It’s still a Prototype!, Using Thymeleaf — Removing template fragments

The Spring tutorial makes the same point about its sample application: after all the form and binding functionality added to the page, the file can still be opened directly in a browser and shows valid HTML with mock data, which is what the tutorial means by calling it a natural template. The official article From HTML to HTML (via HTML) is the original statement of the philosophy. Natural templating is not limited to HTML: the textual modes have their own natural forms (JavaScript and CSS natural templates), and inlining with double square brackets trades naturalness for brevity. Both are covered on the inlining and textual-modes pages of this section.

Some content exists only to make the prototype look right, and some markup is needed by Thymeleaf but would break the static file. The Standard Dialect has three tools for this, all dialect-independent comment syntaxes handled by the parser, plus th:remove for elements.

Source: Using Thymeleaf — Comments and Blocks

The prototype-only block is the answer to the "extra element" problem. A th:block is the one element processor of the Standard Dialect: an attribute container that disappears after its attributes are executed, leaving its content. Written as a plain element it would be an unknown tag in the static file, but wrapped in prototype-only markers it is invisible there and fully active on the server, so the file stays valid:

With two books the output contains only <p>Several books on the shelf.</p>, and with one book nothing at all, as the run above shows. The same trick lets you open a block-level th:each around two table rows (the tutorial uses it for iterations that need more than one <tr>) without adding a forbidden <div> inside a <table>.

Source: Using Thymeleaf — Thymeleaf prototype-only comment blocks, Using Thymeleaf — Synthetic th:block tag

The textual template modes have their own versions of these blocks (/*[+ ... +]*/ and /*[- ... -]*/, plus the /*[# th:if="..."]*/ natural JavaScript and CSS forms); they are described on the textual-modes page of this section and are not interchangeable with the HTML syntaxes above.

A prototype needs more than one row, but the engine iterates only the element that carries th:each. Every extra row stays in the output as if it were real data. The attribute th:remove deletes them when the template runs while leaving them visible in the prototype. It accepts five values, and also any Standard Expression that evaluates to one of them, which makes it usable for conditional removal:

The values are easy to compare on a single template. This one applies each of them to a small block, and the output follows.

Source: Using Thymeleaf — Removing template fragments

Two details are worth keeping in mind. First, th:remove has the lowest precedence among the Standard Dialect attributes, so on an element that also carries th:each, th:if or th:text those run first and the removal happens last (the order is in the tutorial section on attribute precedence, linked below). Second, all-but-first keeps the first child whatever it is, so the iterated template row must come first inside the <tbody>; otherwise the iterated row is the one that gets removed. Compare it with the per-row form used by the tutorial, where each mock row has its own th:remove="all": the <tbody> form is shorter and cannot be forgotten on a newly added mock row.

Source: Using Thymeleaf — Attribute Precedence

Links and resources are where prototypes usually break: an absolute path such as /css/site.css only works when the application serves the file from the web root, and it does not resolve when the file is opened from disk. The natural-template answer is to write both: a relative path in the plain attribute, which the browser uses statically, and a context-relative @{...} link in the th:* attribute, which the server resolves at run time and which replaces the plain one in the output.

This works because of the project layout. In a Boot project the template lives in src/main/resources/templates/natural/books.html and the stylesheet in src/main/resources/static/css/site.css, so the relative path from the template to the stylesheet on disk is ../../static/css/site.css. The same layout at run time serves the file at /css/site.css, which is what @{/css/site.css} produces. A @{/...} URL starting with a slash is context-relative: the engine prepends the application’s context path, so the page keeps working when the application is deployed under a prefix. The same two requests, made with the context path set to /shop, produce:

Source: Using Thymeleaf — Link URLs, Standard URL Syntax

The rules of thumb are:

Natural templates still contain th:* attributes, and for a designer working with an external tool or a team that wants markup free of any engine syntax that is still too much. Since Thymeleaf 3.0 the HTML and XML template modes can decouple the logic: the markup file contains no Thymeleaf code, and the logic lives in a separate logic resource, by default a file next to the template with the same base name and the extension .th.xml:

Each <attr> element performs attribute injection: its sel attribute holds a markup selector (an AttoParser selector, the same syntax as the fragment selectors), and every other attribute of the element is injected into the nodes it selects. The elements can be nested, and the selectors of the inner elements are appended to those of the outer ones, so sel="/tr[0]" inside #booksTable means #booksTable/tr[0] (the first row, indexes start at zero), and td.title inside that means #booksTable/tr[0]//td.title. The pair of files above behaves exactly as this single template would:

Rendered for two books the page is the following. The th:remove="all-but-first" injected on the table dropped the prototype rows that follow the iterated one, so only the data rows remain:

Source: Using Thymeleaf — Decoupled logic: The concept

Natural templates and decoupled logic support two different divisions of labour, and the choice is mostly about who edits which file.

A workable routine for a team using natural templates:

With decoupled logic the routine changes only at the second and third steps: the developer writes a .th.xml file instead of touching the markup, and the designer’s file stays logic-free (a design tool or an external system can even regenerate it). The price is that a contract is needed: the ids and classes the selectors rely on (#booksTable, td.title) or the th:ref names must not be renamed carelessly, because a selector that no longer matches silently injects nothing and the element keeps its prototype text. A short test guards the contract by asserting both that the markup has no logic and that the rendering uses the data:

Source: Using Thymeleaf — Decoupled logic: The concept

The two approaches compare as follows:

For the choice between server-side templates and other front-end styles see Introduction & Architecture. The fragments and layouts pages of this section build on natural templates, since fragments and layouts must also remain viewable by themselves.