Thymeleaf V3.1.2 官方教程：现代服务器端模板引擎解析

thymeleaf

需积分: 0 155 浏览量更新于2024-06-16 收藏 632KB PDF 举报

身份认证购VIP最低享 7 折!

30元优惠券

"官方的Thymeleaf V3.1.2学习文档，详细介绍了Thymeleaf模板引擎的功能和用法。" Thymeleaf是一个现代化的服务器端Java模板引擎，适用于Web和独立环境，支持处理HTML、XML、JavaScript、CSS甚至纯文本。其主要目标是提供一种优雅且高度可维护的方式来创建模板。为了达成这个目标，Thymeleaf引入了“自然模板”（Natural Templates）的概念，允许在模板文件中注入逻辑，同时不会影响模板作为设计原型的使用。这有助于设计师和开发者之间的沟通，缩小他们之间的工作差距。 Thymeleaf从一开始就考虑了Web标准，特别是HTML5，使得你可以创建完全符合验证的模板，如果这是你的需求。它支持处理六种类型的模板，每种类型称为一个“模板模式”： 1. HTML：用于处理HTML文档，是Web应用中最常见的模板模式。 2. XML：处理XML文档，适用于需要XML结构的场景。 3. TEXT：处理纯文本，如电子邮件正文或配置文件等。 4. JAVASCRIPT：处理JavaScript代码，可以动态插入数据到脚本中。 5. CSS：处理CSS样式表，可以动态地生成样式规则。 6. RAW：原始模式，通常用于处理无法归类到其他模式的任何内容。 Thymeleaf的另一个特点是它的表达式语言（Expression Language），它允许在模板中使用变量和表达式来动态地生成内容。例如，`th:text`和`th:href`这样的属性指令可以用来控制文本内容和链接地址。此外，Thymeleaf还提供了条件语句（如`th:if`和`th:unless`）、迭代（如`th:each`）以及与Spring框架的深度集成，使得在MVC应用中使用模板变得更加便捷。在实际应用中，Thymeleaf能够处理视图层的复杂逻辑，同时保持模板的清晰易读。这使得非编程背景的团队成员也能理解模板的内容，从而提高协作效率。Thymeleaf还支持国际化（i18n）和本地化（l10n）功能，帮助构建多语言的应用。 Thymeleaf是一个强大的模板引擎，旨在简化Web开发中的视图层工作，通过自然模板的概念和对Web标准的支持，实现设计和开发的无缝协作，提高项目质量和维护性。通过阅读这份官方学习文档，开发者和设计者可以深入理解Thymeleaf的工作原理和用法，提升他们的技能并优化项目流程。

资源详情

资源推荐

home.welcome=¡Bienvenido a nuestra tienda de comestibles!

But there’s one aspect we still haven’t thought of: what happens if the message text is not completely static? What if, for example, our application knew

who is the user visiting the site at any moment and we wanted to greet them by name?

¡Bienvenido a nuestra tienda de comestibles, John Apricot!

This means we would need to add a parameter to our message. Just like this:

home.welcome=¡Bienvenido a nuestra tienda de comestibles, {0}!

Parameters are specified according to the java.text.MessageFormat standard syntax, which means you can format to numbers and dates as specified in the

API docs for classes in the java.text.* package.

In order to specify a value for our parameter, and given an HTTP session attribute called user , we could have:

Welcome to our grocery store, Sebastian Pepper!

Note that the use of th:utext here means that the formatted message will not be escaped. This example assumes that user.name is already

escaped.

Several parameters can be specified, separated by commas.

The message key itself can come from a variable:

Welcome to our grocery store, Sebastian Pepper!

4.2 Variables

We already mentioned that ${...} expressions are in fact OGNL (Object-Graph Navigation Language) expressions executed on the map of variables

contained in the context.

For detailed info about OGNL syntax and features, you should read the OGNL Language Guide

In Spring MVC-enabled applications OGNL will be replaced with SpringEL, but its syntax is very similar to that of OGNL (actually, exactly the same for

most common cases).

From OGNL’s syntax, we know that the expression in:

Today is: 13 february 2011.

…is in fact equivalent to this:

ctx.getVariable("today");

But OGNL allows us to create quite more powerful expressions, and that’s how this:

Welcome to our grocery store, Sebastian Pepper!

…obtains the user name by executing:

((User) ctx.getVariable("session").get("user")).getName();

But getter method navigation is just one of OGNL’s features. Let’s see some more:

Page 14 of 81

* Access to properties using the point (.). Equivalent to calling property getters.

${person.father.name}

* Access to properties can also be made by using brackets ([]) and writing

* the name of the property as a variable or between single quotes.

${person['father']['name']}

* If the object is a map, both dot and bracket syntax will be equivalent to

* executing a call on its get(...) method.

${countriesByCode.ES}

${personsByName['Stephen Zucchini'].age}

* Indexed access to arrays or collections is also performed with brackets,

* writing the index without quotes.

${personsArray[0].name}

* Methods can be called, even with arguments.

${person.createCompleteName()}

${person.createCompleteNameWithSeparator('-')}

Expression Basic Objects

When evaluating OGNL expressions on the context variables, some objects are made available to expressions for higher flexibility. These objects will be

referenced (per OGNL standard) starting with the # symbol:

#ctx : the context object.

#vars: the context variables.

#locale : the context locale.

So we can do this:

Established locale country: US.

You can read the full reference of these objects in Appendix A.

Expression Utility Objects

Besides these basic objects, Thymeleaf will offer us a set of utility objects that will help us perform common tasks in our expressions.

#execInfo : information about the template being processed.

#messages : methods for obtaining externalized messages inside variables expressions, in the same way as they would be obtained using #{…} syntax.

#uris : methods for escaping parts of URLs/URIs

#conversions : methods for executing the configured conversion service (if any).

#dates : methods for java.util.Date objects: formatting, component extraction, etc.

#calendars : analogous to #dates , but for java.util.Calendar objects.

#temporals : for dealing with dates and times using the java.time API in JDK8+.

#numbers : methods for formatting numeric objects.

#strings : methods for String objects: contains, startsWith, prepending/appending, etc.

#objects : methods for objects in general.

#bools : methods for boolean evaluation.

#arrays : methods for arrays.

#lists : methods for lists.

#sets : methods for sets.

#maps : methods for maps.

#aggregates : methods for creating aggregates on arrays or collections.

#ids : methods for dealing with id attributes that might be repeated (for example, as a result of an iteration).

You can check what functions are offered by each of these utility objects in the Appendix B.

Reformatting dates in our home page

Now we know about these utility objects, we could use them to change the way in which we show the date in our home page. Instead of doing this in our

Page 15 of 81

HomeController :

SimpleDateFormat dateFormat = new SimpleDateFormat("dd MMMM yyyy");

Calendar cal = Calendar.getInstance();

WebContext ctx = new WebContext(webExchange, webExchange.getLocale());

ctx.setVariable("today", dateFormat.format(cal.getTime()));

templateEngine.process("home", ctx, writer);

…we can do just this:

WebContext ctx = new WebContext(webExchange, webExchange.getLocale());

ctx.setVariable("today", Calendar.getInstance());

templateEngine.process("home", ctx, writer);

…and then perform date formatting in the view layer itself:

Today is: 13 May 2011

4.3 Expressions on selections (asterisk syntax)

Not only can variable expressions be written as ${...} , but also as *{...} .

There is an important difference though: the asterisk syntax evaluates expressions on selected objects rather than on the whole context. That is, as long as

there is no selected object, the dollar and the asterisk syntaxes do exactly the same.

And what is a selected object? The result of an expression using the th:object attribute. Let’s use one in our user profile ( userprofile.html ) page:

Name: Sebastian.

Surname: Pepper.

Nationality: Saturn.

</div>

Which is exactly equivalent to:

<div>

Name: Sebastian.

Surname: Pepper.

Nationality: Saturn.

</div>

Of course, dollar and asterisk syntax can be mixed:

Name: Sebastian.

Surname: Pepper.

Nationality: Saturn.

</div>

When an object selection is in place, the selected object will also be available to dollar expressions as the #object expression variable:

Name: Sebastian.

Surname: Pepper.

Nationality: Saturn.

</div>

As said, if no object selection has been performed, dollar and asterisk syntaxes are equivalent.

<div>

Name: Sebastian.

Surname: Pepper.

Nationality: Saturn.

</div>

Page 16 of 81

4.4 Link URLs

Because of their importance, URLs are first-class citizens in web application templates, and the Thymeleaf Standard Dialect has a special syntax for them, the

@ syntax: @{...}

There are different types of URLs:

Absolute URLs: http://www.thymeleaf.org

Relative URLs, which can be:

Page-relative: user/login.html

Context-relative: /itemdetails?id=3 (context name in server will be added automatically)

Server-relative: ~/billing/processInvoice (allows calling URLs in another context (= application) in the same server.

Protocol-relative URLs: //code.jquery.com/jquery-2.0.3.min.js

The real processing of these expressions and their conversion to the URLs that will be output is done by implementations of the

org.thymeleaf.linkbuilder.ILinkBuilder interface that are registered into the ITemplateEngine object being used.

By default, a single implementation of this interface is registered of the class org.thymeleaf.linkbuilder.StandardLinkBuilder , which is enough for both

offline (non-web) and also web scenarios based on the Servlet API. Other scenarios (like integration with non-ServletAPI web frameworks) might need

specific implementations of the link builder interface.

Let’s use this new syntax. Meet the th:href attribute:

<a href="details.html"

th:href="@{http://localhost:8080/gtvg/order/details(orderId=${o.id})}">view</a>

Some things to note here:

th:href is a modifier attribute: once processed, it will compute the link URL to be used and set that value to the href attribute of the <a> tag.

We are allowed to use expressions for URL parameters (as you can see in orderId=${o.id} ). The required URL-parameter-encoding operations will also be

automatically performed.

If several parameters are needed, these will be separated by commas: @{/order/process(execId=${execId},execType='FAST')}

Variable templates are also allowed in URL paths: @{/order/{orderId}/details(orderId=${orderId})}

Relative URLs starting with / (eg: /order/details ) will be automatically prefixed by the application context name.

If cookies are not enabled or this is not yet known, a ";jsessionid=..." suffix might be added to relative URLs so that the session is preserved. This is

called URL Rewriting and Thymeleaf allows you to plug in your own rewriting filters by using the response.encodeURL(...) mechanism from the Servlet

API for every URL.

The th:href attribute allows us to (optionally) have a working static href attribute in our template, so that our template links remained navigable by a

browser when opened directly for prototyping purposes.

As was the case with the message syntax ( #{...} ), URL bases can also be the result of evaluating another expression:

A menu for our home page

Now that we know how to create link URLs, what about adding a small menu in our home page for some of the other pages in the site?

Please select an option

<ol>

<li><a href="product/list.html" th:href="@{/product/list}">Product List</a></li>

<li><a href="order/list.html" th:href="@{/order/list}">Order List</a></li>

<li><a href="subscribe.html" th:href="@{/subscribe}">Subscribe to our Newsletter</a></li>

<li><a href="userprofile.html" th:href="@{/userprofile}">See User Profile</a></li>

</ol>

Server root relative URLs

An additional syntax can be used to create server-root-relative (instead of context-root-relative) URLs in order to link to different contexts in the same

server. These URLs will be specified like @{~/path/to/something}

Page 17 of 81

剩余80页未读，继续阅读