Thymeleaf Tutorial: Chapter 13. Template text modes
Table of contents
Three types of Thymeleaf templates are considered textual: TEXT , JAVASCRIPT and CSS . This distinguishes them from layout pattern modes: HTML and XML .
The key difference between text template modes and markup is that there are no tags in the text template in which to insert logic as attributes, so we must rely on other mechanisms.
The first and most basic of these mechanisms is the investment, which we have already mentioned in the previous chapter. Inlining syntax is the easiest way to display the results of expressions in text pattern mode.
')
Consider a letter:
Even without tags, the above example is a complete and valid Thymeleaf template that can be executed in TEXT mode.
But in order to include more complex logic than simple expressions, we need a new syntax that does not contain tags:
In fact, this is an abbreviated version of a more detailed version:
Notice how this new syntax is based on elements (i.e. processed tags), which are declared as [#element ...] instead of <element ...> . Elements are opened as [#element ...] and closed as [/ element] , and stand-alone tags can be declared by minimizing the open element using / almost equivalent XML tags: [# element… /] .
The standard dialect contains only the processor for one of these elements: the already known th: block , although we could expand our dialects and create new elements in the usual way. In addition, the th: block element ( [#th: block ...] ... [/ th: block] ) is allowed to be abbreviated as an empty string ( [# ...] ... [/] ), so the above block is actually equivalent to:
And this [# th: utext = "$ {item}" /] is equivalent to the built-in unscreened expression, we could just use it to have less code. Thus, we get the first code snippet we saw above:
Please note that text syntax requires a complete balance of elements (no unclosed tags) and quoted attributes — this is more XML style than HTML style.
Let's look at a more complete example of a TEXT template, a text email template:
After execution, the result may be something like:
And one more example in the template mode JAVASCRIPT , the file greeter.js, we treat as a text template, and which we call on HTML pages. Please note that this is not the <script> block in the HTML template, but the .js file is treated as a template itself:
After execution, the result of this may be something like:
Shielded element attributes
To avoid interaction with parts of the template that can be processed in other modes (for example, in text mode that is embedded within an HTML template), Thymeleaf 3.0 allows you to avoid the attributes of the elements in its text syntax. So:
So it would be great in the TEXT template (note the & gt;):
Of course, in a real text template, the example does not make much sense, but it is a good idea if we process the HTML template with the th: inline = “text” block containing the code above, and we want to make sure that our browser does not accept <user. age for the name of the open tag with the static opening of the file as a prototype.
One advantage of this syntax is that it is as extensible as the markup. Developers can still define their dialects using custom elements and attributes, apply a prefix to them (optional), and then use them in text pattern modes:
The JAVASCRIPT and CSS template modes ( not available for TEXT ) allow you to include code between the special comment syntax /*[+...++ * / , so Thymeleaf will automatically uncomment this code when processing the template:
It will be executed as:
You can include expressions inside these comments, and they will be evaluated:
In the same way as for the prototype comment blocks, all three text pattern modes ( TEXT , JAVASCRIPT and CSS ) allow you to instruct Thymeleaf to remove code between special / * [- * / / * -] * / markers:
Or in TEXT mode:
As you can see from the previous chapter, JavaScript and CSS inlining offer the ability to include embedded expressions in JavaScript / CSS comments, for example:
... which is valid javascript, and the executable code might look like this:
The same trick of including embedded expressions inside comments can actually be used for the entire text mode syntax:
This warning in the above code will be shown when the template is statically opened, because it is 100% JavaScript, and also when the template is launched if the user is an administrator. This is equivalent to:
... which is actually code that transforms the original version during the parsing of templates.
Notice, however, that wrapping elements in comments does not clear the lines in which they live (on the right until ; not found), as inlined expressions do. This behavior is reserved for inlined expressions only.
Thus, Thymeleaf 3.0 allows you to create complex JavaScript-scripts and CSS style sheets in the form of natural templates, valid as a prototype, and working template.
13 Text Modes Template
13.1 Text Syntax
Three types of Thymeleaf templates are considered textual: TEXT , JAVASCRIPT and CSS . This distinguishes them from layout pattern modes: HTML and XML .
The key difference between text template modes and markup is that there are no tags in the text template in which to insert logic as attributes, so we must rely on other mechanisms.
The first and most basic of these mechanisms is the investment, which we have already mentioned in the previous chapter. Inlining syntax is the easiest way to display the results of expressions in text pattern mode.
')
Consider a letter:
Dear [(${name})], Please find attached the results of the report you requested with name "[(${report.name})]". Sincerely, The Reporter. Even without tags, the above example is a complete and valid Thymeleaf template that can be executed in TEXT mode.
But in order to include more complex logic than simple expressions, we need a new syntax that does not contain tags:
[# th:each="item : ${items}"] - [(${item})] [/] In fact, this is an abbreviated version of a more detailed version:
[#th:block th:each="item : ${items}"] - [#th:block th:utext="${item}" /] [/th:block] Notice how this new syntax is based on elements (i.e. processed tags), which are declared as [#element ...] instead of <element ...> . Elements are opened as [#element ...] and closed as [/ element] , and stand-alone tags can be declared by minimizing the open element using / almost equivalent XML tags: [# element… /] .
The standard dialect contains only the processor for one of these elements: the already known th: block , although we could expand our dialects and create new elements in the usual way. In addition, the th: block element ( [#th: block ...] ... [/ th: block] ) is allowed to be abbreviated as an empty string ( [# ...] ... [/] ), so the above block is actually equivalent to:
[# th:each="item : ${items}"] - [# th:utext="${item}" /] [/] And this [# th: utext = "$ {item}" /] is equivalent to the built-in unscreened expression, we could just use it to have less code. Thus, we get the first code snippet we saw above:
[# th:each="item : ${items}"] - [(${item})] [/] Please note that text syntax requires a complete balance of elements (no unclosed tags) and quoted attributes — this is more XML style than HTML style.
Let's look at a more complete example of a TEXT template, a text email template:
Dear [(${customer.name})], This is the list of our products: [# th:each="prod : ${products}"] - [(${prod.name})]. Price: [(${prod.price})] EUR/kg [/] Thanks, The Thymeleaf Shop After execution, the result may be something like:
Dear Mary Ann Blueberry, This is the list of our products: - Apricots. Price: 1.12 EUR/kg - Bananas. Price: 1.78 EUR/kg - Apples. Price: 0.85 EUR/kg - Watermelon. Price: 1.91 EUR/kg Thanks, The Thymeleaf Shop And one more example in the template mode JAVASCRIPT , the file greeter.js, we treat as a text template, and which we call on HTML pages. Please note that this is not the <script> block in the HTML template, but the .js file is treated as a template itself:
var greeter = function() { var username = [[${session.user.name}]]; [# th:each="salut : ${salutations}"] alert([[${salut}]] + " " + username); [/] }; After execution, the result of this may be something like:
var greeter = function() { var username = "Bertrand \"Crunchy\" Pear"; alert("Hello" + " " + username); alert("Ol\u00E1" + " " + username); alert("Hola" + " " + username); }; Shielded element attributes
To avoid interaction with parts of the template that can be processed in other modes (for example, in text mode that is embedded within an HTML template), Thymeleaf 3.0 allows you to avoid the attributes of the elements in its text syntax. So:
- Attributes in TEXT template mode will be unshielded HTML
- Attributes in template mode JAVASCRIPT will be javascript-unescaped
- Attributes in CSS template mode will be CSS-unescaped
So it would be great in the TEXT template (note the & gt;):
[# th:if="${120<user.age}"] Congratulations! [/] Of course, in a real text template, the example does not make much sense, but it is a good idea if we process the HTML template with the th: inline = “text” block containing the code above, and we want to make sure that our browser does not accept <user. age for the name of the open tag with the static opening of the file as a prototype.
13.2 Extensibility
One advantage of this syntax is that it is as extensible as the markup. Developers can still define their dialects using custom elements and attributes, apply a prefix to them (optional), and then use them in text pattern modes:
[#myorg:dosomething myorg:importantattr="211"]some text[/myorg:dosomething] 13.3 Comment text blocks for prototype only: add code
The JAVASCRIPT and CSS template modes ( not available for TEXT ) allow you to include code between the special comment syntax /*[+...++ * / , so Thymeleaf will automatically uncomment this code when processing the template:
var x = 23; /*[+ var msg = "This is a working application"; +]*/ var f = function() { ... It will be executed as:
var x = 23; var msg = "This is a working application"; var f = function() { ... You can include expressions inside these comments, and they will be evaluated:
var x = 23; /*[+ var msg = "Hello, " + [[${session.user.name}]]; +]*/ var f = function() { ... 13.4 Text parser-level text blocks: removing code
In the same way as for the prototype comment blocks, all three text pattern modes ( TEXT , JAVASCRIPT and CSS ) allow you to instruct Thymeleaf to remove code between special / * [- * / / * -] * / markers:
var x = 23; /*[- */ var msg = "This is shown only when executed statically!"; /* -]*/ var f = function() { ... Or in TEXT mode:
... /*[- Note the user is obtained from the session, which must exist -]*/ Welcome [(${session.user.name})]! ... 13.5 Natural JavaScript and CSS Templates
As you can see from the previous chapter, JavaScript and CSS inlining offer the ability to include embedded expressions in JavaScript / CSS comments, for example:
... var username = /*[[${session.user.name}]]*/ "Sebastian Lychee"; ... ... which is valid javascript, and the executable code might look like this:
... var username = "John Apricot"; ... The same trick of including embedded expressions inside comments can actually be used for the entire text mode syntax:
/*[# th:if="${user.admin}"]*/ alert('Welcome admin'); /*[/]*/ This warning in the above code will be shown when the template is statically opened, because it is 100% JavaScript, and also when the template is launched if the user is an administrator. This is equivalent to:
[# th:if="${user.admin}"] alert('Welcome admin'); [/] ... which is actually code that transforms the original version during the parsing of templates.
Notice, however, that wrapping elements in comments does not clear the lines in which they live (on the right until ; not found), as inlined expressions do. This behavior is reserved for inlined expressions only.
Thus, Thymeleaf 3.0 allows you to create complex JavaScript-scripts and CSS style sheets in the form of natural templates, valid as a prototype, and working template.
Source: https://habr.com/ru/post/352272/
All Articles