Intégration de Thymeleaf (`spring-boot-starter-thymeleaf`)

Thymeleaf : Un moteur de templates moderne pour Spring

Lorsque vous développez des applications web traditionnelles avec Spring MVC, où le HTML est généré côté serveur, vous avez besoin d'un moyen de créer dynamiquement ces pages HTML en y insérant les données préparées par vos contrôleurs. C'est là qu'interviennent les moteurs de templates. Thymeleaf est un moteur de templates Java moderne, populaire et particulièrement bien intégré avec l'écosystème Spring.

Thymeleaf se distingue par sa philosophie des "templates naturels". Vos fichiers de templates sont simplement des fichiers HTML (ou XML, texte, etc.) qui peuvent être correctement affichés dans un navigateur même sans traitement côté serveur (ils ressemblent à des prototypes statiques). Thymeleaf ajoute ses instructions de traitement via des attributs HTML spécifiques (préfixés par th: par défaut), qui sont ignorés par les navigateurs mais interprétés par le moteur lors du rendu côté serveur.

Spring Boot rend l'intégration de Thymeleaf extrêmement simple grâce à son starter dédié : spring-boot-starter-thymeleaf.

Ajouter la dépendance : La magie du starter

Pour utiliser Thymeleaf dans votre projet Spring Boot, la première étape (et souvent la seule nécessaire pour une configuration de base) est d'ajouter la dépendance spring-boot-starter-thymeleaf à votre fichier de build.

Avec Maven (pom.xml) :

<dependencies>
    <!-- Dépendance pour le Web (inclut Spring MVC, Tomcat embarqué, etc.) -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- Le starter Thymeleaf -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-thymeleaf</artifactId>
    </dependency>

    <!-- Autres dépendances ... -->
</dependencies>

Avec Gradle (build.gradle) :

dependencies {
    // Dépendance pour le Web
    implementation 'org.springframework.boot:spring-boot-starter-web'

    // Le starter Thymeleaf
    implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'

    // Autres dépendances ...
}

Une fois cette dépendance ajoutée, Spring Boot détecte la présence de Thymeleaf et déclenche son mécanisme d'auto-configuration.

Qu'est-ce que l'auto-configuration apporte ?

Le starter spring-boot-starter-thymeleaf, combiné à l'auto-configuration de Spring Boot, configure automatiquement les beans Spring nécessaires pour que Thymeleaf fonctionne de manière transparente avec Spring MVC :

• SpringTemplateEngine : Le bean principal du moteur Thymeleaf, configuré pour s'intégrer à Spring.
• ThymeleafViewResolver : Un bean ViewResolver qui mappe les noms de vues logiques retournés par vos contrôleurs (par exemple, "home", "productList") aux fichiers de templates Thymeleaf réels.
• Configuration par défaut du ViewResolver :
  • Préfixe (Prefix) : classpath:/templates/. Spring cherchera vos fichiers de templates dans le dossier src/main/resources/templates.
  • Suffixe (Suffix) : .html. Il ajoutera automatiquement l'extension .html au nom logique de la vue. Ainsi, si un contrôleur retourne "home", le resolver cherchera classpath:/templates/home.html.
  • Mode de template : HTML (HTML5 par défaut dans les versions récentes).
  • Encodage : UTF-8.
  • Mise en cache (Cache) : Activée par défaut (true) pour la production. Il est fortement recommandé de la désactiver pendant le développement (voir section configuration).
• Intégration du Dialecte Standard de Spring : Le dialecte SpringStandardDialect est automatiquement ajouté au moteur. C'est ce dialecte qui fournit les attributs th: utiles pour interagir avec les fonctionnalités de Spring MVC, comme th:field pour les formulaires, th:object, #{...} pour l'internationalisation (i18n), les expressions d'URL @{...}, et l'accès aux beans Spring via ${@beanName.method()}.
• Autres dialectes optionnels : Si d'autres starters Thymeleaf sont présents (par exemple, `thymeleaf-layout-dialect`, `thymeleaf-extras-springsecurity`), leurs dialectes correspondants sont également auto-configurés.

Grâce à cette auto-configuration, vous pouvez commencer à créer vos contrôleurs et vos templates Thymeleaf immédiatement après avoir ajouté la dépendance.

Exemple simple d'utilisation

1. Créez un contrôleur :

import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;

@Controller
public class GreetingController {

    @GetMapping("/greeting")
    public String greet(@RequestParam(name="name", required=false, defaultValue="World") String name, Model model) {
        // Ajoute l'attribut 'name' au modèle
        model.addAttribute("name", name);
        // Retourne le nom logique de la vue
        return "greeting"; // => Résoudra vers /templates/greeting.html
    }
}

2. Créez le template Thymeleaf correspondant (`src/main/resources/templates/greeting.html`) :

<!DOCTYPE html>
<!-- Important: ajoutez l'espace de noms Thymeleaf -->
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <title>Greeting Page</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
</head>
<body>
    <h1>Hello!</h1>
    <!-- Utilise l'attribut 'name' passé via le Model -->
    <p th:text="'Hello, ' + ${name} + '!'">
        Hello, default user!
    </p>
</body>
</html>

Lorsque vous accédez à /greeting?name=Thymeleaf dans votre navigateur, le contrôleur ajoute "Thymeleaf" au modèle, retourne "greeting", le ThymeleafViewResolver trouve greeting.html, et Thymeleaf traite le template en remplaçant le contenu du paragraphe par "Hello, Thymeleaf!".

Configuration via les propriétés de l'application

Bien que les valeurs par défaut soient souvent suffisantes, vous pouvez personnaliser le comportement de Thymeleaf via votre fichier application.properties ou application.yml. Voici quelques propriétés courantes :

# application.properties

# Désactiver le cache Thymeleaf (TRES UTILE en développement pour voir les changements sans redémarrer)
spring.thymeleaf.cache=false

# Changer le préfixe (si les templates ne sont pas dans /templates/)
# spring.thymeleaf.prefix=classpath:/views/

# Changer le suffixe (si vous utilisez .xhtml par exemple)
# spring.thymeleaf.suffix=.xhtml

# Changer le mode de template (ex: pour des emails texte)
# spring.thymeleaf.mode=TEXT

# Encodage des templates
# spring.thymeleaf.encoding=UTF-8

# Vérifier l'existence du template avant le rendu (peut être désactivé pour perfs)
# spring.thymeleaf.check-template=true

# Vérifier l'existence du template location (ex: /templates/ folder)
# spring.thymeleaf.check-template-location=true

# application.yml
spring:
  thymeleaf:
    cache: false # Désactiver le cache
    # prefix: classpath:/views/
    # suffix: .xhtml
    # mode: TEXT
    # encoding: UTF-8
    # check-template: true
    # check-template-location: true

La désactivation du cache (spring.thymeleaf.cache=false) est particulièrement importante pendant le développement pour pouvoir modifier les fichiers HTML et voir les changements immédiatement en rafraîchissant le navigateur, sans avoir à redémarrer l'application Spring Boot.

Conclusion : Une intégration fluide pour des vues dynamiques

L'intégration de Thymeleaf dans une application Spring Boot est un processus remarquablement simple grâce au starter spring-boot-starter-thymeleaf et à l'auto-configuration. En ajoutant simplement une dépendance, vous disposez d'un moteur de templates puissant et flexible, prêt à être utilisé avec Spring MVC pour générer des vues HTML dynamiques et interactives côté serveur.

Les chapitres suivants exploreront plus en détail la syntaxe et les fonctionnalités avancées de Thymeleaf, notamment pour la gestion des layouts, les formulaires, l'itération, la conditionnalité et l'internationalisation.