Руководство: Thymeleaf + Spring. Часть 1
1. Интеграция Thymeleaf с Spring
2. SpringStandard Диалект
3. Views и View Resolvers
3.1 Views и View Resolvers в Spring MVC
3.2 Views и View Resolvers в Thymeleaf
4. Spring Thyme Seed Starter Manager
4.1 Концепция
4.2 Бизнес слой
4.3 Spring MVC configuration
4.4 Контроллер
4.5 Конфигурирование Conversion Service
5 Отображение Seed Starter Data
6 Создание Форм
6.1 Обработка командного объекта
6.2 Inputs
6.3 Checkbox fields
6.4 Radio Button fields
6.5 Dropdown/List selectors
6.6 Dynamic fields
7 Проверка и сообщения об ошибках
7.1 Field errors
7.2 Все ошибки
7.3 Глобальные ошибки
7.4 Отображение ошибок вне форм
7.5 Богатые объекты ошибок
8 Это все еще прототип!
9 Служба конверсии (The Conversion Service)
9.1 Конфигурирование
9.2 Синтаксис двойной скобки
9.3 Использование в формах
9.4 #conversions объект преобразования
10 Отрисовка фрагментов шаблона Template Fragments (AJAX etc)
10.1 Определение фрагментов в бине представления
10.2 Определение фрагментов в возвращаемом значении контроллера
11 Продвинутые интеграционные фичи
11.1 Интеграция с RequestDataValueProcessor
11.1 Построение URIs к контроллерам
12 Spring WebFlow интеграция
12.2 AJAX фрагменты в Spring WebFlow
В этом руководстве объясняется, как Thymeleaf может быть интегрирован с Spring Framework, особенно (но не только) Spring MVC.
Примеры кода и пример приложения в этом руководстве используют Spring 4.x и соответствующие ему интеграции Thymeleaf, но содержимое этого текста также применимо для Spring 3.x. Если ваше приложение использует Spring 3.x, все, что вам нужно сделать, это заменить пакет org.thymeleaf.spring4 на org.thymeleaf.spring3 в примерах кода.
1. Интеграция Thymeleaf с Spring
Thymeleaf предлагает набор интеграций Spring, которые позволяют использовать его как полнофункциональную замену JSP в приложениях Spring MVC.
Эти интеграции позволят вам:
2. SpringStandard Диалект
Чтобы добиться более легкой и лучшей интеграции, Thymeleaf предоставляет диалект, который специально реализует все необходимые функции для правильной работы с Spring.
Этот конкретный диалект основан на стандартном диалекте Thymeleaf и реализован в классе org.thymeleaf.spring4.dialect.SpringStandardDialect, который фактически происходит от org.thymeleaf.standard.StandardDialect.
Помимо всех функций, уже присутствующих в стандартном диалекте и, следовательно, унаследованных, SpringStandard Dialect предлагает следующие специфические функции:
Пример конфигурации бина:
Или, используя конфигурацию Spring на основе XML:
3. Views и View Resolvers
3.1 Views и View Resolvers в Spring MVC
В Spring MVC есть два интерфейса, которые соответствуют ядру его системы шаблонов:
ViewResolvers — это объекты, отвечающие за получение объектов View для конкретной операции и локали. Обычно контроллеры просят ViewResolvers переслать представление с определенным именем (строка, возвращаемая методом контроллера), а затем все средства разрешения представления в приложении выполняются в упорядоченной цепочке, пока один из них не сможет разрешить это представление, в каком случае объект View возвращается и ему передается управление для рендеризации HTML.
Обратите внимание, что не все страницы в наших приложениях должны быть определены как представления, а только те, поведение которых мы хотим, чтобы мы были нестандартными или настраивались особым образом (например, путем подключения к нему некоторых специальных компонентов). Если ViewResolver запрашивается представление, у которого нет соответствующего bean-компонента (что является распространенным случаем), новый объект View создается ad hoc и возвращается.
Типичная конфигурация JSP + JSTL ViewResolver в приложении Spring MVC из прошлого выглядела так:
Беглого взгляда на его свойства достаточно, чтобы узнать, как он был настроен:
3.2 Views и View Resolvers в Thymeleaf
Thymeleaf предлагает реализации для двух интерфейсов, упомянутых выше:
Конфигурация Resolver Thymeleaf View очень похожа на JSP:
Параметр templateEngine, конечно же, является объектом SpringTemplateEngine, который мы определили в предыдущей главе. Два других (order и viewNames) являются необязательными и имеют то же значение, что и в JSP ViewResolver, который мы видели ранее.
Обратите внимание, что нам не нужны префиксные или суффиксные параметры, потому что они уже указаны в Template Resolver (который, в свою очередь, передается в Template Engine).
А что, если мы хотим определить bean-компонент View и добавить к нему несколько статических переменных? Легко, просто определите для него прототип:
Сделав это, вы сможете запросить этот компонент, выбрав его по имени (в данном случае mainView).
4. Spring Thyme Seed Starter Manager
Исходный код для примеров, показанных в этой и последующих главах этого руководства, можно найти в репозитории GitHub Spring Seyme Seed Starter Manager.
4.1 Концепция
Касательно Thymeleaf — мы большие поклонники thyme, и каждый spring мы готовим наши стартовые наборы с хорошей почвой и нашими любимыми семенами, сажаем их под испанское солнце и терпеливо ждем, пока наши новые растения вырастут.
Но в этом году нам надоело наклеивать ярлыки на стартовые контейнеры для семян, чтобы узнать, какие семена были в каждой ячейке контейнера, поэтому мы решили подготовить приложение, используя Spring MVC и Thymeleaf, чтобы помочь нам каталогизировать наши стартеры: Spring Thyme SeedStarter Менеджер.
Аналогично приложению Good Thymes Virtual Grocery, которое мы разработали в учебном пособии «Использование Thymeleaf», STSM позволит нам продемонстрировать наиболее важные аспекты интеграции Thymeleaf как механизма шаблонов для Spring MVC.
4.2 Бизнес слой
Нам понадобится очень простой бизнес-уровень для нашего приложения. Прежде всего, давайте посмотрим на наши модельные объекты:
Пара очень простых классов обслуживания обеспечит необходимые бизнес-методы. Подобно:
4.3 Spring MVC configuration
Затем нам нужно настроить конфигурацию Spring MVC для приложения, которая будет включать не только стандартные артефакты Spring MVC, такие как обработка ресурсов или сканирование аннотаций, но также создание экземпляров Template Engine и View Resolver.
4.4 Контроллер
Конечно, нам также понадобится контроллер для нашего приложения. Поскольку STSM будет содержать только одну веб-страницу со списком начальных значений и форму для добавления новых, мы напишем только один класс контроллера для всех взаимодействий сервера:
Теперь давайте посмотрим, что мы можем добавить к этому классу контроллера.
Сначала мы добавим некоторые атрибуты модели, которые нам понадобятся на странице:
А теперь самая важная часть контроллера, отображаемые (mapped ) методы: один для отображения страницы формы, а другой для обработки добавления новых объектов SeedStarter.
4.5 Конфигурирование Conversion Service
Чтобы обеспечить простое форматирование объектов Date, а также объектов Variety в нашем слое представления, мы настроили наше приложение таким образом, чтобы объект Spring ConversionService был создан и инициализирован (расширяемым WebMvcConfigurerAdapter) с помощью пары необходимых нам объектов форматирования.
Посмотри еще раз:
Spring formatters are implementations of the org.springframework.format.Formatter interface. For more information on how the Spring conversion infrastructure works, see the docs at spring.io.
Давайте посмотрим на DateFormatter, который форматирует даты в соответствии со строкой форматирования, присутствующей в ключе сообщения date.format наших Messages.properties:
VarietyFormatter автоматически преобразует между нашими объектами Variety и способом, которым мы хотим использовать их в наших формах (в основном, по значениям их полей id):
Мы узнаем больше о том, как эти средства форматирования влияют на способ отображения наших данных в дальнейшем.
Introduction to Using Thymeleaf in Spring
Last modified: December 28, 2020
Get started with Spring 5 and Spring Boot 2, through the Learn Spring course:
1. Introduction
Thymeleaf is a Java template engine for processing and creating HTML, XML, JavaScript, CSS, and text.
In this article, we will discuss how to use Thymeleaf with Spring along with some basic use cases in the view layer of a Spring MVC application.
The library is extremely extensible and its natural templating capability ensures templates can be prototyped without a back-end – which makes development very fast when compared with other popular template engines such as JSP.
2. Integrating Thymeleaf With Spring
Firstly let us see the configurations required to integrate with Spring. The thymeleaf-spring library is required for the integration.
Add the following dependencies to your Maven POM file:
Note that, for a Spring 4 project, the thymeleaf-spring4 library must be used instead of thymeleaf-spring5.
The SpringTemplateEngine class performs all of the configuration steps. You can configure this class as a bean in the Java configuration file:
The templateResolver bean properties prefix and suffix indicate the location of the view pages within the webapp directory and their filename extension, respectively.
The ViewResolver interface in Spring MVC maps the view names returned by a controller to actual view objects. ThymeleafViewResolver implements the ViewResolver interface and is used to determine which Thymeleaf views to render, given a view name.
The final step in the integration is to add the ThymeleafViewResolver as a bean:
3. Thymeleaf in Spring Boot
Spring Boot provides auto-configuration for Thymeleaf by adding the spring-boot-starter-thymeleaf dependency:
No explicit configuration is necessary. By default, HTML files should be placed in the resources/templates location.
4. Displaying Values from Message Source (Property Files)
The th:text=”#
Here is the Thymeleaf HTML code to display the value associated with the key welcome.message:
5. Displaying Model Attributes
5.1. Simple Attributes
The th:text=”$
The HTML code to display the value of serverTime attribute:
5.2. Collection Attributes
If the model attribute is a collection of objects, the th:each tag attribute can be used to iterate over it. Let’s define a Student model class with two fields, id, and name:
Now we will add a list of students as model attribute in the controller class:
Finally, we can use Thymeleaf template code to iterate over the list of students and display all field values:
6. Conditional Evaluation
6.1. if and unless
The th:if=”$
Add a gender field to the Student model:
Suppose this field has two possible values (M or F) to indicate the student’s gender. If we wish to display the words “Male” or “Female” instead of the single character, we could accomplish this by using the following Thymeleaf code:
6.2. switch and case
The th:switch and th:case attributes are used to display content conditionally using the switch statement structure.
The previous code could be rewritten using the th:switch and th:case attributes:
7. Handling User Input
Form input can be handled using the th:action=”@
For the Student class, we can create an input form:
In the above code, /saveStudent is the form action URL and a student is the object that holds the form data submitted.
The StudentController class handles the form submission:
In the code above, the @RequestMapping annotation maps the controller method with URL provided in the form. The annotated method saveStudent() performs the required processing for the submitted form. The @ModelAttribute annotation binds the form fields to the student object.
8. Displaying Validation Errors
The #fields.hasErrors() function can be used to check if a field has any validation errors. The #fields.errors() function can be used to display errors for a particular field. The field name is the input parameter for both these functions.
HTML code to iterate and display the errors for each of the fields in the form:
Instead of field name the above functions accept the wild card character * or the constant all to indicate all fields. The th:each attribute is used to iterate the multiple errors that may be present for each of the fields.
The previous HTML code re-written using the wildcard *:
or using the constant all:
Similarly, global errors in Spring can be displayed using the global constant.
The HTML code to display global errors:
The th:errors attribute can also be used to display error messages. The previous code to display errors in the form can be re-written using th:errors attribute:
9. Using Conversions
The double bracket syntax <<>> is used to format data for display. This makes use of the formatters configured for that type of field in the conversionService bean of the context file.
The name field in the Student class is formatted:
The above code uses the NameFormatter class, configured by overriding the addFormatters() method from the WebMvcConfigurer interface. For this purpose, our @Configuration class overrides the WebMvcConfigurerAdapter class:
The NameFormatter class implements the Spring Formatter interface.
The #conversions utility can also be used to convert objects for display. The syntax for the utility function is #conversions.convert(Object, Class) where Object is converted to Class type.
To display student object percentage field with the fractional part removed:
10. Conclusion
In this tutorial, we’ve seen how to integrate and use Thymeleaf in a Spring MVC application.
We have also seen examples of how to display fields, accept input, display validation errors, and convert data for display. A working version of the code shown in this article is available in a GitHub repository.
Spring MVC Thymeleaf
Сегодя я покажу как создать веб приложение с помощью Spring MVC и серверного Java движка Thymeleaf.
Самое первое с чего начинают учить спринг это написание Spring MVC контроллер класса и отображение html страницы (которая на самом деле не совсем html) с приветствием. В этой статье мы структурируем этот момент и копнем немного глубже: подключим статические ресурсы и немного поработаем с отображением атрибутов на странице.
Если Вы работали с сервлетами и уже писали веб приложения на «чистой» java, без использования фреймворков — то понять этот материал Вам будет значительно проще. Для тех же, кто этого не сделал, я советую хотя бы ознакомиться с теорией. Так как Spring MVC базируется на понятии сервлета и всего что с ним связано.
Если говорить кратко то Spring MVC — это просто удобный способ принимать http запросы и управлять контентом.
Я долго думал как описать Thymeleaf для новичков, чтобы было проще некуда. Перелопатил кучу статтей. Но там почти везде копипаста с официального сайта.
В общем: Thymeleaf это библиотека, которая позволяет хранить html шаблоны на стороне сервера и выдавать их по вызову определенного кода.
Если говорить еще проще, то когда пользователь сидит в Интернете — он скорее всего сидит там через браузер (Хром, Мозила, Опера). То что ему показывается — это html страница, которую он запросил, когда ввел в поисковую строку запрос. Все, что находится на странице, оформленно в виде файла, который имеет расширение html и который состоит из html тегов. Вот такой файл и позволяет хранить на сервере Thymeleaf движок. Он не просто позволяет его хранить там, но также имеет функционал для управления контентом этого файла.
Когда Вы сейчас смотрите на статью, то видите текст, меню, возможно рекламу, кнопки и т.д. Статья — это наполнение страницы. Каждая такая страница со статьей имеет одинаковый вид. Все страницы моего сайта отличаются только наполнением. Внешний вид называют шаблоном. Тоесть все что без текста — это шаблон. Он один по всему сайту. Статьи находятся в базе данных, и когда Вы переходите по определенному урл, сервер смотрит какой контент Вы запрашиваете (по значению урл), берет шаблон и помещает в него текст статьи.
Thymeleaf вместе со Spring MVC позволяют управлять шаблонами веб страниц и наполнением этих самых страниц самым разным контентом и в самый разный способ. В зависимости от запросов польозвателей.
Сейчас я на примере покажу как осуществить то что описано выше.
Первое что я делаю когда хочу создать Spring приложение — иду на spring initializr. Это официальный сайт, который позволяет быстро сгенерировать костяк Spring Boot приложения с необходимыми зависимостями Maven или Gradle. Почему именно Spring Boot? Потому что сейчас это, если можно так сказать, более современная версия спринг фреймворка, которая включает в себя автонастройку. Она избавляет Вас от необходимости писать сложные классы настроек, которые нужно было писать раньше. Более подробно об этом можно почитать в статье Spring: обзор фреймворка для самых маленьких.
Для того чтобы создать приложение используя Spring MVC и Thymeleaf я выбираю соответствующие зависимости:
После этого я просто открываю проект как мавен проект в моем редакторе кода (Intellij idea) и начинаю кодить. Приложение, в котором Вы программируете не имеет значения. Я повторяю это практически в каждой статье. Этот пример можно однаково реализовать как в Intellij idea так и в Eclipse, NetBeans и т.д.
Вот примерная структура моего проекта:
структура Spring Boot MVC проекта
В папке resources находятся директории: static, teamplates. application.properties файл сегодня нас не интересует. Мы не будем добавлять своих настроект в проект.
Папки static, teamplates находятся в нашем проекте не просто так. В Spring Boot автоконфигурации для веб, эти папки являются частью пути к ресурсам: ститическим (css, js, картинки) и шаблонам соответственно.
Первое что можно сделать — создать страницу приветствия или как еще ее иногда называют главную страницу.
Для удобства программистов комманда Spring сделала специальную настройку для главной страницы. Достаточно назвать ее index.html и поместить ее в папку static.
Для примера я добавлю сообщение с приветствием. Вы можете добавить любой шаблон, который пожелаете.
По умолчанию, встроенный в Spring Boot сервер Tomcat стартует с портом 8080. После запуска приложения и перехода в браузере по запросу http://localhost:8080 Вы должны увидеть главную страницу вашего проекта:
Вот так, очень просто и без лишних классов настроек мы смогли добавить страницу приветствия в наше приложение.
Чтобы добавить еще шаблонов по запросу или вывести контент, нам нужно прибегнуть к помощи Thymeleaf и Spring контроллера.
Контроллер — это простой джава класс, который помечен аннотацией @Controller. Этим Вы указываете спринг библиотеке, что данный класс будет принимать входящие http запросы и выдавать соответствующий контент.
За прием запросов будут отвечать методы данного класса, которые помечены соответствующей аннотацией. Как Вы помните существует несколько типов http запросов: GET, POST, PUT, DELETE и т.д. Если Вы этого не знаете — я настоятельно рекомендую почитать немного материала на эту тему. Вот как пример https://www.w3schools.com/tags/ref_httpmethods.asp
Для того, чтобы показать что метод будет принимать определенный запрос из вышеперечисленных, нужно поменить его одной из аннотаций @GetMapping, @PostMapping, @PutMapping и т.д. Один метод будет отвечать за один запрос. Внутрь аннотации нужно добавить атрибут value — часть урл пути запроса.
Например http://localhost:8080/greeting. Чтобы создать метод, который будет принимать такой гет запрос нужно навешать на него аннотацию @GetMapping(«/greeting») или @GetMapping(value = «/greeting»).
Spring контроллер обрабатывает запрос и выдает шаблон или делает редирект на другой запрос. Чтобы выдать шаблон, его сначала нужно создать. В папку templates нужно поместить html файл. Имя этого файла и будет возвращаться в качестве строки контроллер метода. Спринг возьмет имя файла, перейдет в папку templates и попытается найти шаблон по имени.
Движок Thymeleaf возьмет этот html, распарсит его и выдаст на клиент (браузер). Если в файле есть thymeleaf атрибуты — они будут распарсены и отформатированы в соответствии с синтаксисом таймлиф. Об этом немного позже.
Сейчас попытаемся просто выдать страницу по запросу.
Первое: создаем пакет а потом класс: controller, HomeController соответственно. Навешиваем аннотацию @Controller на класс. Создаем метод home(), который пока ничего не принимает на вход и возвращает строку «home_page«. Навешиваем на него аннотацию GetMapping(«/home»).
Переходим в папку templates и создаем файл home_page.html. В содержимое файла можно пока просто поместить приветствие.
Перезапускаем приложение и набираем в браузере http://localhost:8080/home
В результате, мы должны увидеть нашу страницу home_page.
Теперь, попытаемся создать кнопку с формой на главной странице, при нажатии на которую, можно перейти на home страницу и передать в ее содержимое параметр.
Переходим в index.html и создаем простою html форму которая будет вести на /home запрос:
Урл, куда будет вести форма мы указали в атрибуте action. Метод, мы указали в method атрибуте формы. Дальше мы указали input — поле для ввода текста. Это поле имеет имя login. Это очень важно. Так как именно по имени мы будем вынимать параметр в контроллере.
Дальше, мы переходим в HomeController и в методе home() добавляем входной параметр @RequestParam. Это аннотация, которая позволяет извлекать параметр из урл строки. Они принимает name, required атрибуты, которые являются не обязательными. Можно просто назвать имя переменной как и имя ввода формы и тогда параметр name можно не писать. Если Вы ожидаете что этот параметр будет обязательным, то атрибут required тоже можно не писать. Так как он по умолчанию false.
Теперь, когда Вы получили атрибут, с ним можно проводить всевозможные действия (изменить, записать в базу, передать в другой метод и тд). В нашем примере мы просто перешлем его обратно на страницу home_page.
Сделать это нам поможет Model — класс фреймворка спринг, который создан для манипулирования атрибутами. В результате манипулирования с классом Model и его методами мы получили следующий код:
model.addAttribute принимает на вход ключ атрибута и его значение. По аналогии с Map. Таким образом мы приняли атрибут с запроса и передали его на страницу home_page. Теперь осталось только отобразить атрибут на странице с помощью thymeleaf.
Для этого нам нужно в теге html указать xmlns:th=»http://www.thymeleaf.org». Это атрибут пространства имен, который укажет что на этой странице мы используем thymeleaf.
В нужном нам месте отображения login атрибута нужно создать html элемент (любой) и добавить в него th:text=»$
Вышеописанным образом можно передавать и отображать все что угодно: текст, цифры, объекты джава (будет позже) и тд. Таймлиф позволяет нам связать фронтенд с бекендом посредством тесной связи html и java класса.
Еще один важный пункт, который я хочу показать Вам — подключение статических ресурсов: стили CSS, код JS, картинки и тд. Без статических ресурсов создать полноценные веб проект будет не просто.
Первое, что нужно чтобы подключить ресурсы — поместить их в static директорию. Я советую создавать отдельные папки для разных типов статических ресурсов.
Дальше нужно на странице указать ссылку в соответствии с канонами html. Напоминаю, что для CSS это:
для JS:
для изображения:
Для примера я создал 2 файла и поместил в них изменения свойства цвета текста и вывод в консоль браузера сообщения:
CSS файл 
JS файл
Дальше, я подключил их вышеописанным способом к home_page.html:
После перезапуска приложения и перехода на домашнюю страницу я получил результат:
результат подключения стилей и скриптов на Thymeleaf страницу
На данный момент мы научились:
Последнее, что я хочу продемонстрировать — передавать список java объектов на фронтенд и отображать его с помощью технологии Thymeleaf.
Мы будем передавать массив, который состоит из простого объекта с 2 полями. Я специально сделал только два поля чтобы не усложнять пример. Когда Вы увидите как это делать — то сможете передавать и отображать объекты любой сложности.
Я создаю простой джава класс с именем Order. Добавляю ему 2 поля, а также геттеры, сеттеры, equals, hashCode, toString. В результате я получил вот такой код:
Дальше, я создаю отдельный контроллер класс чтобы передавать список ордеров на страницу.
В идеале, список заказов нужно хранить в базе данных, и Вы по желанию можете доделать этот туториал и подлючить базу данных. Я просто создам несколько тестовых объектов заказов и положу их в HashSet.
Дальше, я создаю метод контроллера, который по GET запросу /orders будет возвращать orders_page и атрибут со списком заказов:
После этого, я уже по знакомой Вам схеме, создаю orders_page.html в папке templates и помещаю в него html код для простой таблицы, который я нашел в Интернете. Дальше, я для обхода массива из объектов использую Thymeleaf конструкцию th:block th:each.
Только здесь мы используем Thymeleaf синтаксис. Внутри тега нам доступна переменная order и мы можем с ней работать уже как с простым атрибутом. В результате получился такой код:
После перезапуска приложения и перехода на http://localhost:8080/orders я вижу что мой код работает отлично:
Для большей динамичности и полноты примера я также создам метод для создания объекта Order. Первое, что нужно сделать — добавить форму на страницу заказов. Теперь в форме будет 2 поля: название, цена. На этот раз форма будет отправлять POST запрос на урл /createOrder. Воспользуемся еще одним методом таймлиф th:object=»$<пустой_объект_который_будем_заполнять>». Его нужно поместить как атрибут тега формы. Вместе с action, method. В результате наша страница приобрела вид:
Просто так добавить th:object=»$
Дальше, нужно написать код для приема запроса /createOrder и сохранения заказа в коллекции. Вы можете переделать чтобы заказ сохранялся в базе.
Не забывайте, что создание заказов это POST запрос. Поэтому аннотация будет @PostMapping. Для приема атрибута мы используем аннотацию @ModelAttribute которая идет с библиотекой Spring Web, использование которой мы сейчас изучаем. Метод manageOrders это простой приватный метод, куда я вынес код по добавлению заказов в список:
Ну и самое интересное. После обработки запроса мы можем не только отображать страницы, но и перенаправлять запрос на другой урл. Как видите, здесь используется ключевое слово redirect:. После, указывается путь, по которому мы хотим перенаправить пользователя. В данном случае, я перенаправляю пользователя на /orders запрос. После создания заказа, сработает запрос /orders и программа зайдет в метод orders. В нем мы заново отправим все заказы из списка и заново их отобразим на странице orders_page. Только в этот раз заказов будет на один больше, так как в коллекции уже будет созданный заказ.
Это все, что я хотел показать в рамках этого туториала. Теперь Вы сможете запрограммировать веб приложение на Java без лишней возни и заморочек с настройками.
Я также записал видео по этому гайду: