Thymeleaf – szablony w Spring – przykłady

Thymeleaf to jeden z najbardziej zaawansowanych i elastycznych silników szablonów dla Spring Framework, umożliwiający deweloperom tworzenie dynamicznych aplikacji webowych na bazie naturalnych szablonów HTML. Dzięki koncepcji „Natural Templating” szablony mogą być wyświetlane jako statyczne prototypy w przeglądarce i jednocześnie przetwarzane dynamicznie po stronie serwera. Pozwala to na efektywną współpracę między designerami a programistami, którzy integrują logikę biznesową przy użyciu specjalnych atrybutów Thymeleaf.

Thymeleaf obsługuje wiele formatów szablonów, w tym:

• html,
• xml,
• text,
• javascript,
• css,
• raw.

HTML jest najczęściej wykorzystywanym formatem w aplikacjach webowych.

Integracja z Spring Framework obejmuje pełne wsparcie dla Spring Expression Language (SpEL), komponentów Spring MVC, walidacji formularzy oraz automatycznej konfiguracji przez Spring Boot.

Fundamenty integracji Thymeleaf z Spring Framework

Integracja Thymeleaf z Spring Framework jest jednym z najdojrzalszych rozwiązań dla warstwy prezentacji w aplikacjach Java. Dedykowane biblioteki integracyjne:

• thymeleaf-spring5 – dla Spring 5.x,
• thymeleaf-spring6 – dla najnowszych wersji Spring Framework.

Pozwalają na wykorzystanie pełnej funkcjonalności Spring MVC wraz z możliwościami renderowania dynamicznych szablonów HTML.

Najważniejsze zalety tej integracji to:

• wykorzystanie Spring Expression Language (SpEL) w szablonach Thymeleaf,
• pełne wsparcie automatycznego wiązania danych i walidacji przy użyciu Bean Validation API,
• integracja z Spring Security dla logiki autoryzacji bezpośrednio w widokach.

Dzięki temu deweloperzy mogą w prosty sposób stosować mechanizmy MVC oraz internationalization, a także szybko dostosować warstwę prezentacji do wymagań biznesowych.

Konfiguracja i uruchomienie Thymeleaf w Spring Boot

Aby skonfigurować Thymeleaf w Spring Boot, wystarczy skorzystać z auto-konfiguracji:

• Dodanie zależności spring-boot-starter-thymeleaf do pliku Maven lub Gradle,
• umieszczenie szablonów HTML w src/main/resources/templates,
• umieszczenie plików statycznych w src/main/resources/static,
• pliki konfiguracyjne w src/main/resources.

Spring Boot automatycznie konfiguruje niezbędne komponenty takie jak SpringTemplateEngine czy ThymeleafViewResolver, co umożliwia szybkie rozpoczęcie pracy.

Dalsze dostosowanie możliwe jest w plikach application.properties lub application.yml, gdzie zdefiniujesz m.in.:

• spring.thymeleaf.cache – kontrola cache’owania szablonów;
• spring.thymeleaf.template-loader-path – ścieżka do szablonów;
• spring.thymeleaf.suffix – rozszerzenie plików szablonów.

Wyłączenie cache’owania (spring.thymeleaf.cache=false) w środowisku development pozwala natychmiast widzieć efekty zmian bez restartu aplikacji.

Struktura i składnia szablonów Thymeleaf

Szablony Thymeleaf mają strukturę zgodną z HTML5. Dzięki temu:

• są poprawne już jako czysty HTML,
• mogą być otwierane bezpośrednio w przeglądarce,
• specjalne atrybuty th: (np. th:text, th:if, th:each) są ignorowane przez przeglądarkę, lecz interpretowane przez silnik na serwerze.

Najważniejsze atrybuty Thymeleaf:

• th:text – zamienia zawartość na dane dynamiczne;
• th:utext – wyświetla nieescapowany HTML;
• th:if – warunkowe renderowanie;
• th:each – iteracja przez kolekcje.

Wyrażenia Thymeleaf umożliwiają:

• dostęp do danych modelu przez ${…};
• wyrażenia selekcyjne *{…} do pracy z obiektem kontekstowym;
• internationalization przez #{…};
• generowanie linków przez @{…};
• włączanie fragmentów ~{…}.

Domyślnie dane przekazywane przez th:text są escapowane, chroniąc przed XSS (Cross-Site Scripting).

Wiązanie danych i wyrażenia zmiennych

System wyrażeń umożliwia bezpośredni, bezpieczny dostęp do danych przekazywanych z kontrolera:

• ${…} – standardowy dostęp do danych modelu,
• *{…} – dostęp uproszczony w obrębie fragmentu lub formularza,
• obsługa kolekcji, map, tablic i obiektów domenowych.

Podczas pracy z formularzami warto używać mechanizmu th:object oraz th:field dla automatycznego wiązania pól i ich wartości. Thymeleaf automatycznie zapobiega NullPointerException oraz oferuje wsparcie dla różnych typów danych.

Dostępne są także obiekty użytkowe:

• #strings – operacje na tekstach;
• #numbers – formatowanie liczb;
• #dates – praca z datami;
• #lists – operacje na listach.

Dzięki pełnej integracji ze Spring Expression Language (SpEL) możesz stosować zaawansowane wyrażenia i dostęp do beanów Spring.

Obsługa formularzy i walidacja danych

Obsługa formularzy HTML w Thymeleaf zintegrowana ze Spring pozwala w prosty sposób tworzyć rozbudowane formularze webowe, automatycznie wiązać dane z obiektami i wyświetlać komunikaty o błędach.

Organizacja typowego formularza wygląda następująco:

• th:object – przypisuje formularz do obiektu modelu;
• th:field – automatycznie wiąże pola formularza z właściwościami obiektu;
• th:if oraz th:errors – wyświetlanie błędów walidacji.

Walidacja za pomocą Bean Validation API i adnotacji @Valid jest obsługiwana automatycznie. System zachowuje wprowadzone przez użytkownika wartości w przypadku błędów walidacji.

Formularze mogą korzystać z:

• dynamicznego budowania kolekcji obiektów,
• obsługi różnorodnych typów pól (checkbox, radio button, select),
• ochrony przed CSRF (jeśli Spring Security jest obecny, tokeny CSRF są obsługiwane automatycznie).

Logika warunkowa i iteracje w szablonach

Do kontrolowania widoczności i struktury elementów Thymeleaf oferuje zaawansowaną logikę warunkową i iteracyjną:

• th:if – renderuje element, jeśli wyrażenie jest prawdziwe;
• operatory logiczne – and, or, not dla tworzenia złożonych warunków;
• th:switch/th:case – odpowiednik konstrukcji switch/case w językach programowania, pozwalający w prosty sposób obsługiwać wiele rozgałęzień.

Brak bezpośredniego „else” zastępuje się negacją wyrażenia w kolejnym elemencie.

Dla iteracji przez kolekcje lub tablice stosuje się th:each. Zmienna iteracyjna pozwala na dostęp do właściwości takich jak:

• index,
• count,
• size,
• even/odd,
• first/last.

Atrybut th:each obsługuje wszystkie typowe kolekcje Java oraz optymalizuje wydajność również przy dużych zbiorach danych.

Zarządzanie układem i fragmenty szablonów

Do budowy modularnych, wielokrotnego użytku komponentów Thymeleaf oferuje zarządzanie fragmentami:

• th:insert – wstawia fragment do istniejącego elementu;
• th:replace – całkowicie zastępuje element hosta fragmentem;
• th:fragment – umożliwia tworzenie wielokrotnego użytku fragmentów HTML;
• parameterization – przekazywanie zmiennych do fragmentów.

Dla zarządzania layoutem na większą skalę można używać Thymeleaf Layout Dialect:

• layout:decorate – wskazuje szablon główny (dekorator);
• layout:fragment – definiuje obszary przeznaczone do wypełnienia przez konkretne strony;
• obsługa dziedziczenia układu,
• dynamiczne wybieranie layoutów podczas działania aplikacji.

Umożliwia to spójność oraz redukcję duplikacji kodu nawet w dużych projektach enterprise.

Internationalization i obsługa komunikatów

Aby przygotować aplikację na wielojęzyczność, Thymeleaf wraz ze Spring wykorzystuje:

• pliki messages.properties jako źródła tłumaczeń;
• specjalne klucze lokalizacyjne (np. messages_pl.properties);
• wyrażenia Thymeleaf #{…} w szablonach dla obsługi tekstów zgodnych z wybranym językiem użytkownika.

Spring obsługuje hierarchiczne wyszukiwanie kluczy, a wyrażenia mogą być parametrówane (przekazywanie wartości dynamicznych w tłumaczeniach).

Dostępne są różne strategie wykrywania Locale:

• SessionLocaleResolver – przechowywanie języka w sesji,
• CookieLocaleResolver – poprzez cookies,
• AcceptHeaderLocaleResolver – detekcja z nagłówka HTTP przeglądarki.

Zaawansowane obiekty użytkowe, takie jak #dates czy #numbers, pozwalają na formatowanie dat, liczb i walut zgodnie z lokalizacją użytkownika.

Zaawansowane funkcjonalności i najlepsze praktyki

Thymeleaf w aplikacjach Spring oferuje szereg zaawansowanych funkcji:

• wielopoziomowe mechanizmy cache’owania – zarówno dla szablonów, jak i fragmentów;
• pełna integracja z Spring Security na poziomie szablonów;
• możliwość tworzenia własnych dialektów i atrybutów (IDialect, IProcessor);
• wsparcie dla prekompilacji szablonów dla optymalizacji wydajności;
• narzędzia do debugowania oraz logowania procesu renderowania szablonów.

Najlepsze praktyki obejmują stosowanie fragmentów dla powtarzalnych komponentów, unikanie złożonych wyrażeń logicznych i regularne monitorowanie jakości szablonów.

Integracja z nowoczesnym ekosystemem webowym

Nowoczesne aplikacje webowe wymagają efektywnej integracji z narzędziami frontendowymi i pipeline’ami buildowania:

• zarządzanie zasobami statycznymi w src/main/resources/static oraz obsługa cache i kompresji przez Spring Boot,
• obsługa frameworków CSS i JS takich jak Bootstrap czy jQuery przez WebJars lub lokalne zależności,
• integracja z Webpack/Gulp – pipeline generuje zasoby w katalogu static dla Spring Boot,
• dynamiczne określanie ścieżek do zasobów za pomocą wyrażeń @{…} i cache busting,
• pełna kompatybilność z podejściem server-side rendering, Progressive Web App (PWA), a także z aplikacjami hybrydowymi i SPA.

System fragmentów oraz warunkowe renderowanie mogą być używane do implementacji responsywnych, dostępnych interfejsów zgodnych ze standardami accessibility.

Testowanie i quality assurance

Testowanie Thymeleaf w aplikacjach Spring obejmuje:

• testy jednostkowe kontrolerów za pomocą MockMvc,
• testy integracyjne całych przepływów z użyciem @SpringBootTest, TestRestTemplate lub WebTestClient,
• automatyczne testy przeglądarkowe (Selenium WebDriver, HtmlUnit),
• statyczna analiza kodu i lintery dla szablonów,
• testy wydajności renderowania i obsługi dużego ruchu (JProfiler, VisualVM, JMeter, Gatling).

Dokumentacja i stosowanie code review dla szablonów zwiększa jakość oraz ułatwia utrzymanie rozbudowanych aplikacji webowych.