forked from thymeleaf/thymeleaf.github.io
-
Notifications
You must be signed in to change notification settings - Fork 0
/
standarddialect5minutes.html
executable file
·377 lines (305 loc) · 14 KB
/
standarddialect5minutes.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Getting started with the Standard dialects in 5 minutes - Thymeleaf: java XML/XHTML/HTML5 template engine</title>
<link rel="stylesheet" type="text/css" media="all" href="css/thymeleaf.css" />
<link rel="shortcut icon" href="http://www.thymeleaf.org/favicon.ico" />
<script type="text/javascript" src="https://apis.google.com/js/plusone.js">
{lang:'en', parsetags:'explicit'}
</script>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-1276954-9']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
<script type="text/javascript" src="sh/scripts/shCore.js"></script>
<script type="text/javascript" src="sh/scripts/shBrushXml.js"></script>
<script type="text/javascript" src="sh/scripts/shBrushJava.js"></script>
<link href="sh/styles/shCore.css" rel="stylesheet" type="text/css" />
<link href="sh/styles/shThemeThymeleaf.css" rel="stylesheet" type="text/css" />
</head>
<body lang="en" dir="ltr">
<div id="page">
<div id="menu">
<ul>
<li><a href="index.html" title="Home">Home</a></li>
<li><a href="features.html" title="Features">Features</a></li>
<li><a href="download.html" title="Download">Download</a></li>
<li><a href="documentation.html" title="Documentation">Documentation</a></li>
<li><a href="ecosystem.html" title="Ecosystem">Ecosystem</a></li>
<li><a href="http://forum.thymeleaf.org" title="User Forum">User Forum</a></li>
<li><a href="issuetracking.html" title="Issue Tracking">Issue Tracking</a></li>
</ul>
</div>
<div id="header">
<a href="index.html" title="Thymeleaf home"><img src="images/thymeleaflogonameverysmall.png" class="logo" alt="Thymeleaf Template Engine"/></a>
</div>
<div id="breadcrumb">
<a href="index.html">thymeleaf</a>
::
<a href="documentation.html">documentation</a>
::
tutorials and guides
::
<span class="current">getting started with the standard dialects in 5 minutes</span>
</div>
<div id="content">
<h1>Getting started with the Standard dialects in 5 minutes</h1>
<p>
This guide will take you through some of the most important concepts you
need to know to understand a Thymeleaf template written in the <i>Standard</i> or <i>SpringStandard</i> dialects.
It is not a substitute for the tutorials — which are much more comprehensive —
but it will teach you enough for getting the feel of the technology.
</p>
<h2>Standard dialects?</h2>
<p>
Thymeleaf is very, very extensible, and it allows you to define your own sets of
template attributes (or even tags) with the names you want, evaluating the expressions you want
in the syntax you want and applying the logic you want. It's more like a <i>template engine framework</i>.
</p>
<p>
Out of the box, nevertheless, it comes with something called <i>the standard dialects</i>
(named <i>Standard</i> and <i>SpringStandard</i>) that
define a set of features which should be more than enough for most scenarios. You can identify
when these standard dialects are being used in a template because it will contain attributes
starting with the <kbd>th</kbd> prefix, like <kbd><span th:text="..."></kbd>.
</p>
<p>
Note that the <i>Standard</i> and the <i>SpringStandard</i> dialects are almost
identical, except that <i>SpringStandard</i> includes specific features for integrating
into Spring MVC applications (like, for example, using <i>Spring Expression Language</i> for
expression evaluation instead of <i>OGNL</i>).
</p>
<p>
Also note we usually refer to features in the Standard dialects when we talk about Thymeleaf without
being more specific.
</p>
<h2>Standard Expression syntax</h2>
<p>
Most Thymeleaf attributes allow their values to be set as or containing <i>expressions</i>,
which we will call <i>Standard Expressions</i> because of the dialects they are used in.
These can be of four types:
</p>
<ul>
<li>Variable expressions</li>
<li>Selection or <i>asterisk</i> expressions</li>
<li>Text externalization or <i>internationalization</i> expressions</li>
<li>URL expressions</li>
</ul>
<h3>Variable expressions</h3>
<p>
Variable expressions are OGNL expressions —or Spring EL if you're using <i>SpringStandard</i>— executed
on the map of context variables —also called <i>model attributes</i> in Spring jargon. They look like this:
</p>
<script type="syntaxhighlighter" class="brush:html;gutter:false"><![CDATA[
${session.user.name}
]]></script>
<p>
And you will find them as attribute values or as a part of them, depending on the attribute:
</p>
<script type="syntaxhighlighter" class="brush:html;gutter:false"><![CDATA[
<span th:text="${book.author.name}">
]]></script>
<script type="syntaxhighlighter" class="brush:html;gutter:false"><![CDATA[
<li th:each="book : ${books}">
]]></script>
<h3>Selection (asterisk) expressions</h3>
<p>
Selection expressions are just like variable expressions, except they will be executed on a
previously selected object instead of the whole context variables map. They look like this:
</p>
<script type="syntaxhighlighter" class="brush:html;gutter:false"><![CDATA[
*{customer.name}
]]></script>
<p>
The object they act on is specified by a <kbd>th:object</kbd> attribute:
</p>
<script type="syntaxhighlighter" class="brush:html"><![CDATA[
<div th:object="${book}">
...
<span th:text="*{title}">...</span>
...
</div>
]]></script>
<h3>Text externalization expressions</h3>
<p>
Text externalization (often called <i>internationalization</i>) allows us to
retrieve locale-specific messages from external sources (<kbd>.properties</kbd> files), referencing
them by a key and (optionally) applying a set of parameters.
</p>
<script type="syntaxhighlighter" class="brush:html;gutter:false"><![CDATA[
#{main.title}
]]></script>
<script type="syntaxhighlighter" class="brush:html;gutter:false"><![CDATA[
#{message.entrycreated(${entryId})}
]]></script>
<p>
You can find them in templates like:
</p>
<script type="syntaxhighlighter" class="brush:html"><![CDATA[
<table>
...
<th th:text="#{header.address.city}">...</th>
<th th:text="#{header.address.country}">...</th>
...
</table>
]]></script>
<h3>URL expressions</h3>
<p>
URL expressions are meant to add useful context and session info to the URLs, a process usually
called <i>URL rewriting</i>.
</p>
<script type="syntaxhighlighter" class="brush:html;gutter:false"><![CDATA[
@{/order/list}
]]></script>
<p>
URLs can also take parameters:
</p>
<script type="syntaxhighlighter" class="brush:html;gutter:false"><![CDATA[
@{/order/details(id=${orderId})}
]]></script>
<p>
And be relative (in which case no application context will be added to the URL):
</p>
<script type="syntaxhighlighter" class="brush:html;gutter:false"><![CDATA[
@{../documents/report}
]]></script>
<p>
Let's see these expressions in context:
</p>
<script type="syntaxhighlighter" class="brush:html;gutter:false"><![CDATA[
<form th:action="@{/createOrder}">
]]></script>
<script type="syntaxhighlighter" class="brush:html;gutter:false"><![CDATA[
<a href="main.html" th:href="@{/main}">
]]></script>
<p>
From this last example, see how Thymleaf allows us to set an <kbd>href</kbd> value for static
prototyping, letting our templates link to each other nicely when directly open in a browser,
and at the same time with <kbd>th:href</kbd> we can specify the URL that will be set as
<kbd>href</kbd> when Thymeleaf really executes the template.
</p>
<h3>Literals and operations</h3>
<p>
A good bunch of types of literals and operations are available:
</p>
<ul>
<li>Literals:
<ul>
<li>Text literals: <kbd>'one text'</kbd>, <kbd>'Another one!'</kbd>,...</li>
<li>Number literals: <kbd>0</kbd>, <kbd>34</kbd>, <kbd>3.0</kbd>, <kbd>12.3</kbd>,...</li>
<li>Boolean literals: <kbd>true</kbd>, <kbd>false</kbd></li>
<li>Null literal: <kbd>null</kbd></li>
<li>Literal tokens: <kbd>one</kbd>, <kbd>sometext</kbd>, <kbd>main</kbd>,...</li>
</ul>
</li>
<li>Text operations:
<ul>
<li>String concatenation: <kbd>+</kbd></li>
<li>Literal substitutions: <kbd>|The name is ${name}|</kbd></li>
</ul>
</li>
<li>Arithmetic operations:
<ul>
<li>Binary operators: <kbd>+</kbd>, <kbd>-</kbd>, <kbd>*</kbd>, <kbd>/</kbd>, <kbd>%</kbd></li>
<li>Minus sign (unary operator): <kbd>-</kbd></li>
</ul>
</li>
<li>Boolean operations:
<ul>
<li>Binary operators: <kbd>and</kbd>, <kbd>or</kbd></li>
<li>Boolean negation (unary operator): <kbd>!</kbd>, <kbd>not</kbd></li>
</ul>
</li>
<li>Comparisons and equality:
<ul>
<li>Comparators: <kbd>></kbd>, <kbd><</kbd>, <kbd>>=</kbd>, <kbd><=</kbd> (<kbd>gt</kbd>, <kbd>lt</kbd>, <kbd>ge</kbd>, <kbd>le</kbd>)</li>
<li>Equality operators: <kbd>==</kbd>, <kbd>!=</kbd> (<kbd>eq</kbd>, <kbd>ne</kbd>)</li>
</ul>
</li>
<li>Conditional operators:
<ul>
<li>If-then: <kbd>(if) ? (then)</kbd></li>
<li>If-then-else: <kbd>(if) ? (then) : (else)</kbd></li>
<li>Default: <kbd>(value) ?: (defaultvalue)</kbd></li>
</ul>
</li>
</ul>
<h3>Expression preprocessing</h3>
<p>
One last thing to know about expressions is there is something called <i>expression
preprocessing</i>, specified between <kbd>__</kbd>, which looks like this:
</p>
<script type="syntaxhighlighter" class="brush:html;gutter:false"><![CDATA[
#{selection.__${sel.code}__}
]]></script>
<p>
What we are seeing there is a variable expression (<kbd>${sel.code}</kbd>) that will be
executed first and which result — let's say, "<kbd>ALL</kbd>" — will be used
as a part of the real expression to be executed afterwards, in this case an
internationalization one (which would look for the message with key <kbd>selection.ALL</kbd>).
</p>
<h2>Some basic attributes</h2>
<p>
Let's have a look at a couple of the most basic attributes in the Standard Dialect.
Starting with <kbd>th:text</kbd>, which just replaces the body of a tag
(notice again the prototyping abilities here):
</p>
<script type="syntaxhighlighter" class="brush:html;gutter:false"><![CDATA[
<p th:text="#{msg.welcome}">Welcome everyone!</p>
]]></script>
<p>
Now <kbd>th:each</kbd>, which repeats the element it's in as many times as specified
by the array or list returned by its expression, creating also an inner variable for
the iteration element with a syntax equivalent to that of a Java <i>foreach</i> expression:
</p>
<script type="syntaxhighlighter" class="brush:html;gutter:false"><![CDATA[
<li th:each="book : ${books}" th:text="${book.title}">En las Orillas del Sar</li>
]]></script>
<p>
Lastly, Thymeleaf includes lots of <kbd>th</kbd> attributes for specific XHTML and HTML5
attributes which just evaluate their expressions and set the value of these attributes
to their result. Their names mimic those of the attributes which values they set:
</p>
<script type="syntaxhighlighter" class="brush:html;gutter:false"><![CDATA[
<form th:action="@{/createOrder}">
]]></script>
<script type="syntaxhighlighter" class="brush:html;gutter:false"><![CDATA[
<input type="button" th:value="#{form.submit}" />
]]></script>
<script type="syntaxhighlighter" class="brush:html;gutter:false"><![CDATA[
<a th:href="@{/admin/users}">
]]></script>
<h2>Want to know more?</h2>
<p>
Then the <a href="documentation.html"><i>"Using Thymeleaf"</i></a> tutorial is what you're looking for!
</p>
</div>
<div id="footer">
<div id="googleplus">
<div id="plusone-div" class="plusone"></div>
<script type="text/javascript">
gapi.plusone.render('plusone-div',{"size": "small", "count": "true", "href": "http://www.thymeleaf.org"});
</script>
</div>
<div id="twitter">
<a href="http://twitter.com/thymeleaf" class="twitter-follow-button" data-show-count="false">Follow @thymeleaf</a>
<script src="http://platform.twitter.com/widgets.js" type="text/javascript"></script>
</div>
<div id="copy">
Copyright © The <a href="team.html">THYMELEAF Team</a>. See <a href="documentation.html">applicable licenses</a>.
</div>
</div>
</div>
<script type="text/javascript">
SyntaxHighlighter.all();
</script>
</body>
</html>