前言
这个教程介绍了Thymeleaf与Spring框架的集成，特别是SpringMvc框架。
注意Thymeleaf支持同Spring框架的3.和4.版本的集成，但是这两个版本的支持是封装在thymeleaf-spring3和thymeleaf-spring4这两个独立的库中，项目中需要根据实际情况分别引用。
样例代码针对的是spring4.，但一般情况下，spring3.也可以无缝使用，所需要的仅仅是改变一下引用库。
1 Thymeleaf同Spring的整合
Thymeleaf与Spring进行整合后，可以在SpringMVC应用中完全替代JSP文件。
集成后你将：
*就像控制JSP一样，使用SpringMvc的@Controller注解来映射Thymeleaf的模板文件。
*在模板中使用SpringEL表达式来替换OGNL
*在模板中创建的表单，完全支持Beans和结果的绑定，包括使用PropertyEditor，转换，和验证等。
*可以通过Spring来管理国际化文件显示国际化信息。
*注意，在使用本教程之前，您应该充分了解Thymeleaf的标准方言。
2 Spring标准方言
为了更加方便，更快捷的集成，Thymeleaf提供了一套能够与Spring正确工作的特有方言。
这套方言基于Thymeleaf标准方言实现，它在类 org.thymeleaf.spring.dialect.SpringStandardDialect 中，事实上，他继承于 org.thymeleaf.standard.StandardDialect
除了已经出现在标准方言中的所有功能，Spring中还有以下特点：
*不适用OGNL，而是SpringEL做完变量表达式，因此，所有的${...}和*{...}表达式将用Spring的表达式引擎进行处理。
*访问应用context中的beans可以使用SpringEL语法:${@myBean.doSomething()}
*基于表格处理的新属性：th:field,th:errors和th:errorclass,除此还有一个th:object的新实现，允许它使用表单命令选择器（？？）。
*一个新的表达式：#themes.code(...)，相当于jsp自定义标签中的spring:theme。
*在spring4.0集成中的一个新的表达式:#mvc.uri(...)，相当于jsp自定义标签中的spring:mvcUrl(...)
注意，上述这些方言特性是不能再普通的TemplateEngine对象中使用的，应该配置一个org.thymeleaf.spring4.SpringTemplateEngine来执行。
其他thymeleaf基础使用方法部分不在叙述。
创建表单
处理命令对象
SpringMVC的表单支持bean就是命令对象，这个对象通过对象领域模型的方式提供get和set方法，在浏览器建立获取用户输入值的输入框架。
Thymeleaf需要你显示的在form标签内通过th:object属性指定命令对象：
1 <form action="#" th:action="@{/seedstartermng}" th:object="${seedStarter}" method="post">
2 ...
3 </form>
这个th:object与其他的的地方用途是一直的，但是事实上在这种特定情况下，为了与SpringMVC框架的正确整合增加了一些特定的限制:
1.在form标签中的th:object的值必须是变量表达式(...),只能指定属性模型属性的名字，而不能使用属性导航，这意味着，表达式...),只能指定属性模型属性的名字，而不能使用属性导航，
这意味着，表达式 {seedStarter}是正确的，而${seedStarter.data}则不是。
2.一个form标签内只能指定一个th:object属性，这与html中form标签不能嵌套的特性相一致。
input
下面是如何将一个input插入到表单中
<input type="text" th:field="*{datePlanted}" />
th:field 的属性，这是SpringMVC集成的一个重要特征，它帮你完成了表单bean和输入框之间的繁重的绑定工作。可以看出他在from中的路径属性和SpringMVC的jsp标签库一样。
th:field 属性的不同行为取决于它所附加的不同标签，包括 <input> , <select> 或 <textarea>
<input type="text" id="datePlanted" name="datePlanted" th:value="*{datePlanted}" />
th:field 还可能会注册一个Spring的转换服务，包括之前我们看到的 DateFormatter （甚至这个表达式中没使用双大括号），因此，这个日期也将被正确的格式化。
th:field 的值必须使用选择表达式，这样将在这个环境中使用表单bean，而不是上下文变量或SpringMVC的模型属性。
相反对于 th:object 这类，它的表达式可以使用属性导航(事实上在JSP的 <form:input 标签中，可以使用任何的路径属性表达式)
注意th:field属性也可以在HTML5的的新增类型中使用，如 <input type="datetime"> ， <input type="color">
复选框
th:field 也可以用在 checkbox
1 <div>
2 <label th:for="${#ids.next('covered')}" th:text="#{seedstarter.covered}">已种植</label>
3 <input type="checkbox" th:field="*{covered}" />
4 </div>
#ids.next("covered") 方法，用于当该id的复选框执行的时候获取它的id值。
那么为什么我们需要这个字段的id属性动态生成呢？因为复选框可能是多值的，因此它会给id值添加一个序列号后缀(内部使用 #ids.seq(...)
我们可以看看多值的复选框：
1 <ul>
2 <li th:each="feat : ${allFeatures}">
3 <input type="checkbox" th:field="*{features}" th:value="${feat}" />
4 <label th:for="${#ids.prev('features')}"
5 th:text="#{${'seedstarter.feature.' + feat}}">Heating</label>
6 </li>
7 </ul>
th:value
一般情况下，它的输出为：
1 <ul>
2 <li>
3 <input id="features1" name="features" type="checkbox"
4 value="SEEDSTARTER_SPECIFIC_SUBSTRATE" />
5 <input name="_features" type="hidden" value="on" />
6 <label for="features1">Seed starter-specific substrate</label>
7 </li>
8 <li>
9 <input id="features2" name="features" type="checkbox"
10 value="FERTILIZER" />
11 <input name="_features" type="hidden" value="on" />
12 <label for="features2">Fertilizer used</label>
13 </li>
14 <li>
15 <input id="features3" name="features" type="checkbox"
16 value="PH_CORRECTOR" />
17 <input name="_features" type="hidden" value="on" />
18 <label for="features3">PH Corrector used</label>
19 </li>
20 </ul>
#ids.prev(....) 函数允许我们把检索最后一个序列值，生成的一个特定的id。
用不着担心那些隐藏域的名称为"_features"：这是为了避免浏览器将未选中的复选框的值在表单提交是没有自动发送而故意添加的。
还应注意到，如果我们的表单bean中的feature属性已经包含了一些特定的值，那么th:field还将会自动在相应的标签中增加checked="checked"属性。
单选框
单选框的用法和一个非布尔值的多选框使用方式类似，只是他不是多选：
1 <ul>
2 <li th:each="ty : ${allTypes}">
3 <input type="radio" th:field="*{type}" th:value="${ty}" />
4 <label th:for="${#ids.prev('type')}" th:text="#{${'seedstarter.type.' + ty}}">Wireframe</label>
5 </li>
6 </ul>
下拉列表
下拉列表包含两个部分:<select>标签和它包含的<option>标签。在创建这种表单域的时候，只有<select>标签需要导入th:field属性，但 th:value 属性却在 <option>
使用类型作为下拉列表：
1 <select th:field="*{type}">
2 <option th:each="type : ${allTypes}"
3 th:value="${type}"
4 th:text="#{${'seedstarter.type.' + type}}">Wireframe</option>
5 </select>
这段代码理解起来很容易，只是注意属性优先级让我们可以在option标签内使用th:each属性。
动态域
由于SpringMVC的高级表单绑定功能，使得我们可以使用复杂的SpringEL表达式来绑定动态表单域到表单bean中。这将允许我们在 SeedStarter bean
为了做到这一点，我们需要在控制器中提供一些新的映射方法，它将根据我们的特定请求的参数来决定添加或删除一行我们定义的.
1 @RequestMapping(value="/seedstartermng", params={"addRow"})
2 public String addRow(final SeedStarter seedStarter, final BindingResult bindingResult) {
3 seedStarter.getRows().add(new Row());
4 return "seedstartermng";
5 }
6
7 @RequestMapping(value="/seedstartermng", params={"removeRow"})
8 public String removeRow(
9 final SeedStarter seedStarter, final BindingResult bindingResult,
10 final HttpServletRequest req) {
11 final Integer rowId = Integer.valueOf(req.getParameter("removeRow"));
12 seedStarter.getRows().remove(rowId.intValue());
13 return "seedstartermng";
14 }
现在给form添加一个动态table
1 <table>
2 <thead>
3 <tr>
4 <th th:text="#{seedstarter.rows.head.rownum}">Row</th>
5 <th th:text="#{seedstarter.rows.head.variety}">Variety</th>
6 <th th:text="#{seedstarter.rows.head.seedsPerCell}">Seeds per cell</th>
7 <th>
8 <button type="submit" name="addRow" th:text="#{seedstarter.row.add}">Add row</button>
9 </th>
10 </tr>
11 </thead>
12 <tbody>
13 <tr th:each="row,rowStat : *{rows}">
14 <td th:text="${rowStat.count}">1</td>
15 <td>
16 <select th:field="*{rows[__${rowStat.index}__].variety}">
17 <option th:each="var : ${allVarieties}"
18 th:value="${var.id}"
19 th:text="${var.name}">Thymus Thymi</option>
20 </select>
21 </td>
22 <td>
23 <input type="text" th:field="*{rows[__${rowStat.index}__].seedsPerCell}" />
24 </td>
25 <td>
26 <button type="submit" name="removeRow"
27 th:value="${rowStat.index}" th:text="#{seedstarter.row.remove}">Remove row</button>
28 </td>
29 </tr>
30 </tbody>
31 </table>
这里出现了很多东西，但都不难理解，除了这一句：
1 <select th:field="*{rows[__${rowStat.index}__].variety}">
2 ...
3 </select>
__${...}__
1 <select th:field="*{rows[rowStat.index].variety}">
2 ...
3 </select>
row[rowStat.index] (而不是 row[0],row[1] )而不是行集合中的正确位置，这就是为什么在这里需要预处理。
让我们看看产生的html后按"添加行"按钮几次：
1 <tbody>
2 <tr>
3 <td>1</td>
4 <td>
5 <select id="rows0.variety" name="rows[0].variety">
6 <option selected="selected" value="1">Thymus vulgaris</option>
7 <option value="2">Thymus x citriodorus</option>
8 <option value="3">Thymus herba-barona</option>
9 <option value="4">Thymus pseudolaginosus</option>
10 <option value="5">Thymus serpyllum</option>
11 </select>
12 </td>
13 <td>
14 <input id="rows0.seedsPerCell" name="rows[0].seedsPerCell" type="text" value="" />
15 </td>
16 <td>
17 <button name="removeRow" type="submit" value="0">Remove row</button>
18 </td>
19 </tr>
20 <tr>
21 <td>2</td>
22 <td>
23 <select id="rows1.variety" name="rows[1].variety">
24 <option selected="selected" value="1">Thymus vulgaris</option>
25 <option value="2">Thymus x citriodorus</option>
26 <option value="3">Thymus herba-barona</option>
27 <option value="4">Thymus pseudolaginosus</option>
28 <option value="5">Thymus serpyllum</option>
29 </select>
30 </td>
31 <td>
32 <input id="rows1.seedsPerCell" name="rows[1].seedsPerCell" type="text" value="" />
33 </td>
34 <td>
35 <button name="removeRow" type="submit" value="1">Remove row</button>
36 </td>
37 </tr>
38 </tbody>
验证和错误信息
让我们看看当有错误的时候如何给一个表单域一个CSS类：
1 <input type="text" th:field="*{datePlanted}"
2 th:class="${#fields.hasErrors('datePlanted')}? fieldError" />
#fields.hasErrors(...) 函数接受一个表达式参数(datePlanted),返回一个布尔值告诉field该字段是否有验证错误。
我们可以根据他们各自的field获取所有的错误：
1 <ul>
2 <li th:each="err : ${#fields.errors('datePlanted')}" th:text="${err}" />
3 </ul>
th:errors ,一个专门用于创建一个通过制定选择器筛选的错误列表的属性，通过
1 <input type="text" th:field="*{datePlanted}" />
2 <p th:if="${#fields.hasErrors('datePlanted')}" th:errors="*{datePlanted}">Incorrect date</p>
简单错误基础css样式，th:errorclass
在上边的例子中，如果字段有错误，将为表单的input域设置一个css类，因为这种方式很常见，Thymeleaf提供了一个特定的属性为 th:errorclass
应用于form域的标签(input,select,textarea等)，它将从现有的name属性或th:field属性字段的名词相同的属性，如果发生错误，则将制定的css类追加到标签中。
<input type="text" th:field="*{datePlanted}" class="small" th:errorclass="fieldError" />
如果datePlanted发生错误,则：
<input type="text" id="datePlanted" name="datePlanted" value="2013-01-01" class="small fieldError" />
全部错误
如果我们想要在form中显示所有的错误呢？我们只需要通过'*'或'all'(等价)来查询 #field.hasErrors(...) 方法和 #field.errors(...)
1 <ul th:if="${#fields.hasErrors('*')}">
2 <li th:each="err : ${#fields.errors('*')}" th:text="${err}">Input is incorrect</li>
3 </ul>
在上边的例子中，我们得到所有的错误并迭代他们：
1 <ul>
2 <li th:each="err : ${#fields.errors('*')}" th:text="${err}" />
3 </ul>
建立一个以<Enter>分隔的列表：
1 <p th:if="${#fields.hasErrors('all')}" th:errors="*{all}">Incorrect date</p>
#field.hasErrors("") 等效的属性 #fields.hasAnyErrors() 和 #fields.errors() 的等效的 #fields.allErrors()
1 <div th:if="${#fields.hasAnyErrors()}">
2 <p th:each="err : ${#fields.allErrors()}" th:text="${err}">...</p>
3 </div>
全局错误
Spring表单还有一种错误，全局错误，都是些不与窗体的任何特定字段关联的错误。
Thymeleaf提供了一个global的常量来访问这些错误。
1 <ul th:if="${#fields.hasErrors('global')}">
2 <li th:each="err : ${#fields.errors('global')}" th:text="${err}">Input is incorrect</li>
3 </ul>
Incorrect date以及等效的 #field.hasGlobalErrors() 和 #field.globalErrors()
1 <div th:if="${#fields.hasGlobalErrors()}">
2 <p th:each="err : ${#fields.globalErrors()}" th:text="${err}">...</p>
3 </div>
在表单外部显示错误
表单验证错误也可以在表单外部显示，方法是通过变量(即${...})的内部选择变量(*{...})增加表单bean的名字作为前缀的方式。
1 <form>
2 <div th:errors="${myForm}">...</div>
3 <div th:errors="${myForm.date}">...</div>
4 <div th:errors="${myForm.*}">...</div>
5 <div th:if="${#fields.hasErrors('${myForm}')}">...</div>
6 <div th:if="${#fields.hasErrors('${myForm.date}')}">...</div>
7 <div th:if="${#fields.hasErrors('${myForm.*}')}">...</div>
8 <form th:object="${myForm}">
9 ...
10 </form>
富错误对象
Thymeleaf提供了以bean的形式(代替单纯的String)提供错误信息的能力，包括fieldName(String),message(String),和global(String)属性的错误。这些错误可以通过工具方法#fields.datailedErrors()来实现：
1 <ul>
2 <li th:each="e : ${#fields.detailedErrors()}" th:class="${e.global}? globalerr : fielderr">
3 <span th:text="${e.global}? '*' : ${e.fieldName}">The field name</span> |
4 <span th:text="${e.message}">The error message</span>
5 </li>
6 </ul>
转换服务
配置
就像前文所说，Thymeleaf可以在上下文中注册一个转换服务，再次看一下他的配置信息
1 <?xml version="1.0" encoding="UTF-8"?>
2 <beans ...>
3 ...
4 <mvc:annotation-driven conversion-service="conversionService" />
5 ...
6 <!-- **************************************************************** -->
7 <!-- CONVERSION SERVICE -->
8 <!-- Standard Spring formatting-enabled implementation -->
9 <!-- **************************************************************** -->
10 <bean id="conversionService"
11 class="org.springframework.format.support.FormattingConversionServiceFactoryBean">
12 <property name="formatters">
13 <set>
14 <bean class="thymeleafexamples.stsm.web.conversion.VarietyFormatter" />
15 <bean class="thymeleafexamples.stsm.web.conversion.DateFormatter" />
16 </set>
17 </property>
18 </bean>
19 ...
20 </beans>
${{...}}语法
转换服务可以通过 ${{...}} 语法很轻松的实现对象到字符串的转换或格式化:
变量语法 ${{...}}
选择变量语法 *{{...}}
例如，将一个Integer型转换为字符串类型，并通过逗号来分隔:
1 <p th:text="${val}">...</p>
2 <p th:text="${{val}}">...</p>
返回结果为：
1 <p>1234567890</p>
2 <p>1,234,567,890</p>
表单中使用
我们之前看到的每一个th:field属性都将始终使用转换服务：
<input type="text" th:field="*{datePlanted}" />
等效于：
<input type="text" th:field="*{{datePlanted}}" />
注意这是唯一一种在表达式中使用单大括号的转换服务。
#conversions工具对象
conversions工具对象表达式允许手动执行转换服务：
<p th:text="${'Val: ' + #conversions.convert(val,'String')}">...</p>
工具对象表达式的语法为：
conversions.convert(Object,Class) :将对象转换为指定的类
conversions.convert(Object,String)
渲染片段模板
Thymeleaf提供了将一个模板只渲染一部分，并作为一个片段返回的能力。
这是一个非常有用的组件化工具，比如，它可以用于执行AJAX的Controller的调用，用于在已经加载的浏览器中返回一个片段标签（如用于更新选择，启用禁用按钮等）。
片段渲染可以使用Thymeleaf的片段规范:一个实现了 org.thymeleaf.fragment.IFragmentSpec
最常用的一个实现是 org.thymeleaf.standard.fragment.StandardDOMSelectorFragmentSpec
在视图bean中指定片段
视图bean是在应用程序上下文中声明的 org.thymeleaf.spring4.view.ThymeleafView
1 <bean name="content-part" class="org.thymeleaf.spring4.view.ThymeleafView">
2 <property name="templateName" value="index" />
3 <property name="fragmentSpec">
4 <bean
5 class="org.thymeleaf.standard.fragment.StandardDOMSelectorFragmentSpec"
6 c:selectorExpression="content" />
7 </property>
8 </bean>
通过上边的bean的定义，如果controller返回一个content-part(bean的名字)，
1 @RequestMapping("/showContentPart")
2 public String showContentPart() {
3 ...
4 return "content-part";
5 }
Thymeleaf将只返回index模板的content片段。一旦前缀后缀都设置并匹配，那么它可能为/WEB-INF/templates/index.html，
1 <!DOCTYPE html>
2 <html>
3 ...
4 <body>
5 ...
6 <div th:fragment="content">
7 只有这里渲染！！
8 </div>
9 ...
10 </body>
11 </html>
th:fragment
1 <bean name="content-part" class="org.thymeleaf.spring4.view.ThymeleafView">
2 <property name="fragmentSpec">
3 <bean class="org.thymeleaf.standard.fragment.StandardDOMSelectorFragmentSpec"
4 c:selectorExpression="#content" />
5 </property>
6 <property name="templateName" value="index" />
7 </bean>
同样完美的适用：
1 <!DOCTYPE html>
2 <html>
3 ...
4 <body>
5 ...
6 <div id="content">
7 只有这里渲染！！
8 </div>
9 ...
10 </body>
11 </html>
通过控制权的返回值指定片段
不声明一个视图bean，可以从控制器自己就可以使用与片段相同的语法，类似于th:insert,th:rplace属性等，如：
1 @RequestMapping("/showContentPart")
2 public String showContentPart() {
3 ...
4 return "index :: content";
5 }
当然，同样可以使用基于DOM选择器的功能，所有我们也可以是选择使用基于标准的HTML属性，如id="content"
1 @RequestMapping("/showContentPart")
2 public String showContentPart() {
3 ...
4 return "index :: #content";
5 }
也可以使用参数：
1 @RequestMapping("/showContentPart")
2 public String showContentPart() {
3 ...
4 return "index :: #content ('myvalue')";
5 }
与RequestDataValueProcessor集成
现在Thymeleaf无缝的与Spring的RequestDataValueProcessor接口集成，这个接口允许拦截链接URLS，表达URLS和表达域的值，以及为了启用安全，如抵御CSRF而自动透明的添加一些隐藏域。
在应用的上下文中可以简单的配置RequestDataValueProcessor：
1 <?xml version="1.0" encoding="UTF-8"?>
2 <beans xmlns="http://www.springframework.org/schema/beans"
3 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4 xsi:schemaLocation="http://www.springframework.org/schema/beans
5 http://www.springframework.org/schema/beans/spring-beans-3.1.xsd">
6
7 ...
8
9 <bean name="requestDataValueProcessor"
10 class="net.example.requestdata.processor.MyRequestDataValueProcessor" />
11
12 </beans>
Thymeleaf将通过这种方式使用它：
RequestDataValueProcessor.processUrl(...)
在渲染表单的action属性之前，th:action会调用 RequestDataValueProcessor.processAction(...) ，另外他会检查标签，因为一般来说这是使用action的唯一一个地方，并且在的关闭标签之前执行 RequstDataValueProcessor.getExtraHiddenFields(...)
RequestDataProcessor.processFormFieldValue(...) ,除非在这个标签中存在了th:field(这时候th:field属性起作用)
当存在th:field的时候，在渲染value属性之前会调用 RequestDataValueProcessor.processFormFieldValue(...) 处理这个属性值(<textarea>处理内容值)
此功能只有Spring3.x以后使用
绑定地址到Controller
在Spring4.1之后的版本中，Spring允许通过注解直接从从视图链接到控制器，而不需要知道这些控制器映射的URI.
#mvc.url(...)
比如
1 public class ExampleController {
2 @RequestMapping("/data")
3 public String getData(Model model) { ... return "template" }
4 @RequestMapping("/data")
5 public String getDataParam(@RequestParam String type) {
6 ...
7 return "template" }
8 }
下边是一个链接到它的方法：
1 <a th:href="${(#mvc.url('EC#getData')).build()}">获取Data参数</a>
2 <a th:href="${(#mvc.url('EC#getDataParam').arg(0,'internal')).build()}">获取Data参数</a>
Spring WebFlow的集成
基础配置
Thymeleaf-spring4集成包包括与Spring WebFlow 2.3.x的集成
WebFlow包括当特定的事件(过渡)被触发时渲染页面片段的一些Ajax的功能，未来让Thymeleaf参加这些Ajax请求，我们将使用一个不通过的视图解析器的实现，它这样配置：
1 <bean id="thymeleafViewResolver" class="org.thymeleaf.spring4.view.AjaxThymeleafViewResolver">
2 <property name="viewClass" value="org.thymeleaf.spring4.view.FlowAjaxThymeleafView" />
3 <property name="templateEngine" ref="templateEngine" />
4 </bean>
ViewFactoryCreator
1 <bean id="mvcViewFactoryCreator"
2 class="org.springframework.webflow.mvc.builder.MvcViewFactoryCreator">
3 <property name="viewResolvers" ref="thymeleafViewResolver"/>
4 </bean>
在这里可以指定模板的视图状态
1 <view-state id="detail" view="bookingDetail">
2 ...
3 </view-state>
在上边的实例中，bookingDetail是Thymeleaf模板通常使用的一个方式，是模板引擎内任何模板解析器都可以懂的
Ajax片段
WebFlow的片段规范允许片段通过标签呈现，就像这样：
1 <view-state id="detail" view="bookingDetail">
2 <transition on="updateData">
3 <render fragments="hoteldata"/>
4 </transition>
5 </view-state>
这些片段(即hoteldata)可以是逗号分隔的列表标记在th:fragment标签中。
1 <div id="data" th:fragment="hoteldata">
这里内容替换</div>
永远记住，指定的片段必须有一个id属性，这样浏览器运行的SpringJavaScript库才能对标签进行替换。
标签，也可以通过DOM选择器设定：
1 <view-state id="detail" view="bookingDetail">
2 <transition on="updateData">
3 <render fragments="[//div[@id='data']]"/>
4 </transition>
5 </view-state>
这将意味着th:fragment不在需要：
1 <div id="data">
2 This is a content to be changed
3 </div>
而出发updateData后转换的代码：
1 <script type="text/javascript" th:src="@{/resources/dojo/dojo.js}"></script>
2 <script type="text/javascript" th:src="@{/resources/spring/Spring.js}"></script>
3 <script type="text/javascript" th:src="@{/resources/spring/Spring-Dojo.js}"></script>
4
5 ...
6
7 <form id="triggerform" method="post" action="">
8 <input type="submit" id="doUpdate" name="_eventId_updateData" value="Update now!" />
9 </form>
10
11 <script type="text/javascript">
12 Spring.addDecoration(
13 new Spring.AjaxEventDecoration({
14 formId:'triggerform',
15 elementId:'doUpdate',
16 event:'onclick'
17 }));
18 </script>
