Textual Template Modes

The mode of a template decides which parser reads it and which escaping applies to the values written into it. The Standard Dialect processors exist for every mode, but the syntax differs.

The same three modes are also what the engine switches to inside an HTML template when you declare th:inline="text", "javascript" or "css" on an element; the page on inlining shows that route. This page is about the other route: a file that is a textual template from its first character. How a resolver picks the mode:

Source: Javadoc: AbstractConfigurableTemplateResolver

setResolvablePatterns keeps this resolver from claiming view names such as books/list, which must still go to the HTML resolver. Template names like text/overdue.txt keep their extension because the resolver has no suffix. A small service renders them to a String:

Source: Using Thymeleaf — Textual template modes

Without tags there is nowhere to put th:each. So the textual modes define an element syntax built on square brackets instead of angle brackets. An element is opened as [#name attributes], closed as [/name], and a standalone element is written [#name attributes /]. Attributes are quoted, and the elements must be balanced: this is closer to XML than to HTML.

The Standard Dialect ships a processor for exactly one such element, th:block, and allows its name to be omitted, so these three templates mean the same thing:

Source: Using Thymeleaf — Textual syntax

The element [# th:utext="${book}" /] is exactly an inlined unescaped expression, which is why the shortest form is the usual one. The th: attributes inside these elements are processed by the same Standard Dialect processors as in HTML, so the attributes described in the pages on iteration and conditionals (th:each, th:if, th:unless, th:switch, th:case, th:with) work on [# ...] elements.

Rendered with member set to Ada and books set to Dune and Solaris:

Source: Using Thymeleaf — Textual syntax

Look at the blank lines: they are part of the text. The line holding [# th:each=...] and the line holding [/] each end with a newline, and those newlines stay in the output, so the template above produces an extra blank line before the first item, one between iterations and one before the closing line. When the exact layout matters (CSV, a config file, a fixed-width report), put the opening and closing elements at the end of neighbouring content lines instead of on lines of their own:

Rendered:

Source: Using Thymeleaf — Textual syntax

An attribute inside a textual element is written in a file whose mode may be different from the file that finally gets served. The typical case: a th:inline="text" block inside an HTML template, opened from disk as a prototype. A raw < in [# th:if="${120<user.age}"] would make the browser take <user.age for the name of an open tag. Since Thymeleaf 3.0 the attributes of textual elements are therefore unescaped by the engine according to the mode of the template they belong to:

With age set to 130:

Source: Using Thymeleaf — Escaped element attributes

In a pure text file the < is never needed, and writing it makes the template harder to read; the escape exists for text that lives inside another document. The scenario it protects, an HTML page that contains a text block, looks like this:

Rendered with age set to 130:

Source: Using Thymeleaf — Escaped element attributes

The element syntax is as extensible as the tag syntax. A dialect can contribute element processors that apply to TemplateMode.TEXT, JAVASCRIPT or CSS, give them a prefix, and then be used as [#prefix:name attr="..."]...[/prefix:name]. The official example is a [#myorg:dosomething myorg:importantattr="211"]some text[/myorg:dosomething] element. Writing one is the same job as writing a processor for HTML (the guide on extending Thymeleaf covers it): subclass AbstractElementTagProcessor, choose the template mode, and declare the processor in an AbstractProcessorDialect. The dialect below adds a shout:upper element to TEXT templates:

Registering the dialect as a Spring bean is enough in Spring Boot; the auto-configured engine adds every IDialect bean:

Rendered with count set to 2:

Source: Extending Thymeleaf — Element Tag Processors

The processor in this example is tied to TemplateMode.TEXT; to serve JAVASCRIPT and CSS as well, register one processor per mode. A processor registered only for HTML does not run in the textual modes, so the pages that extend Thymeleaf are where to look for the dialect basics, the processor precedence rules and the other kinds of processors.

The JAVASCRIPT and CSS modes (not TEXT) recognise the special comment /*[+ ... +]*/. When the file is opened as a plain script or style sheet, the browser sees a comment and skips it. When Thymeleaf processes the file it removes the comment markers and keeps what is inside, so the code becomes live:

The statement var mode = ... is a comment in the browser’s static view and a normal statement in the output:

Expressions inside the block are evaluated too, so the block can use [[${...}]]. Typical uses are a fragment of initialisation that only exists in production or a call that needs the real session, in a script that would otherwise load in a designer’s browser with no backend.

Source: Using Thymeleaf — Textual prototype-only comment blocks

The opposite convention works in all three textual modes (TEXT, JAVASCRIPT and CSS). Code between /*[- */ and /* -]*/ is removed by the parser before any processing happens, so it exists only in the static file. Use it for placeholder content a designer needs to see:

A comment of the form /*[- ... -]*/ removes just that comment, which is also the tidy way to leave a note in a text template that must not reach the output:

Rendered with member set to Ada:

Source: Using Thymeleaf — Textual parser-level comment blocks

The pair mirrors the HTML <!--/* ... */--> blocks: the parser-level comment is removed before the processors run, while the prototype-only one is kept and uncommented. Neither appears in the page an end user sees.

The inlining chapter introduced the trick of wrapping an inlined expression in a comment and following it with a literal that the static file shows. The textual syntax goes further: the whole element syntax can be wrapped in comments, so a script containing control flow is still plain, valid JavaScript when opened from disk:

Opened statically, the alert is valid JavaScript and runs. Rendered, it stays for admins and disappears for everyone else. Thymeleaf converts this at parse time into the plain [# th:if="${user.admin}"] ... [/] form. The same wrapper iterates, which is how a script can be written with a sample row and rendered with real ones:

With greetings set to Hello and Hola, rendered:

Source: Using Thymeleaf — Natural JavaScript and CSS templates

One rule differs from the inlined expressions: an inlined output expression in a comment also removes the static literal that follows it, which is why console.log(/*[[${greeting}]]*/ "Hello") prints the greeting and not both. Wrapping an element in comments does not clean the rest of its line; that clean-up is reserved for inlined output expressions only.

CSS templates work the same way. Because [[...]] in the CSS modes escapes CSS characters, a colour such as #0b6e4f comes out as \#0b6e4f when written with the escaped form. Use the unescaped [(...)] for values you trust, such as an accent colour from your own configuration, and keep the escaped form for text:

Rendered with accent set to #0b6e4f:

Source: Using Thymeleaf — Natural JavaScript and CSS templates

The \#0b6e4f in the second rule is a CSS-escaped hash, so the browser does not read it as a colour and ignores the declaration. That is the reason --accent above uses the unescaped form: for a trusted token such as a colour from your own configuration use [(...)], and keep [[...]] for text. Never feed an untrusted value to [(...)] in CSS or JavaScript.

A rendered script is a normal HTTP response whose body happens to come from a template. In Spring MVC the controller renders to a String and declares the media type; because the content varies per request or per deployment, do not let proxies cache it by accident:

The string Sci-Fi "Classics" came out as the JavaScript string literal "Sci-Fi \"Classics\"": in JAVASCRIPT mode [[...]] writes a JavaScript literal, with quotes and escapes, not the raw text. That is what makes var name = [[${shelfName}]]; safe where building the string by hand would not be. The Spring Security default requires a login for these URLs, so a script that has to load on the login page needs its path permitted explicitly (the pages on Spring Security cover how).

Source: Using Thymeleaf — Natural JavaScript and CSS templates

Rendered with two loans, and with host books.example.org and paths /api and /static:

Source: Using Thymeleaf — Textual template modes

The tutorial notes that the TEXT mode is subject to stricter expression evaluation restrictions than the markup modes, and Appendix D of the tutorial lists TEXT-mode output among the contexts where the restricted mode applies. In that mode, instantiating objects with new and referencing static classes with T(...) are forbidden:

Source: Using Thymeleaf — Appendix D: Expression Restrictions

Restricted mode is a safety net, not a licence to render attacker-written templates: keep the template text under your control. The page on template security has the full list of what the restricted mode forbids and the Thymeleaf CVEs fixed in 3.1.4 and 3.1.5.