4. La vue et son modèle

Jusqu'ici, les actions fabriquaient elles-mêmes leur réponse : du texte, du JSON, quelques balises HTML écrites dans une chaîne de caractères. Dans une application MVC, c'est le rôle d'une vue : un fichier qui décrit la page HTML, avec des emplacements pour les données que lui transmet l'action, le modèle de la vue. [Spring MVC] ne fournit pas lui-même de langage de vues : il sait travailler avec plusieurs moteurs de vues ([Thymeleaf], [FreeMarker], [Mustache], [JSP]...). Ce cours utilise [Thymeleaf], le moteur de vues le plus répandu avec [Spring MVC], que [Spring Boot] sait configurer tout seul.

Une vue [Thymeleaf] est un fichier [.html] ordinaire : un fichier HTML valide, que l'on peut ouvrir tel quel dans un navigateur. Les données y sont insérées par des attributs supplémentaires, préfixés par [th:] ([th:text], [th:if], [th:each]...), que [Thymeleaf] exécute sur le serveur, puis retire de la page. C'est ce que [Thymeleaf] appelle des modèles naturels ([natural templates]) : un graphiste peut travailler sur la vue sans lancer l'application, et le développeur y ajoute les attributs [th:]. C'est une différence avec [Razor], le moteur de vues d'[ASP.NET Core MVC], qui mélange HTML et code [C#] précédé du caractère [@].

4.1. Exemple 13 : une première vue

Pour utiliser [Thymeleaf], il suffit d'ajouter une dépendance au fichier [pom.xml] de l'exemple :

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

lignes 3-6 : le starter [spring-boot-starter-thymeleaf]. Un starter est une dépendance « tout compris » : elle apporte [Thymeleaf], son intégration à [Spring] (la bibliothèque [thymeleaf-spring6]), et la configuration automatique de [Spring Boot] qui les relie à [Spring MVC]. Il n'y a rien d'autre à écrire : pas de version (elle est fixée par le projet parent [spring-boot-starter-parent]), pas de classe de configuration.

Le modèle de la vue est une simple classe. Le fichier [models/PageModele.java] :

package exemple13.models;

// le modèle de la vue : les données que l'action transmet à la vue
public record PageModele(String titre, String message, String heure) {
}

ligne 4 : un record [Java] (cf. exemple 03) est une classe dont les champs sont fixés, une fois pour toutes, par le constructeur : ici trois chaînes [titre], [message] et [heure]. Le compilateur écrit pour nous le constructeur et les accesseurs qui lisent les champs. Attention : ces accesseurs portent le nom du champ ([titre()]), et non [getTitre()] comme dans une classe [JavaBean] (cf. exemple 08). C'est une façon concise d'écrire une classe qui ne fait que transporter des données.

Le fichier [controllers/VuesController.java] :

package exemple13.controllers;

import java.time.LocalTime;
import java.time.format.DateTimeFormatter;
import java.util.Map;

import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.servlet.ModelAndView;

import exemple13.models.PageModele;

// @Controller : les actions rendent le NOM d'une vue
@Controller
public class VuesController {

    private static final DateTimeFormatter HEURE = DateTimeFormatter.ofPattern("HH:mm:ss");

    // Model : le modèle de la vue, un dictionnaire rempli par l'action ;
    // la chaîne rendue est le nom de la vue : templates/vues/index.html
    @GetMapping("/")
    public String index(Model model) {
        PageModele modele = new PageModele(
                "Ma première vue",
                "Cette page a été fabriquée par Thymeleaf, sur le serveur.",
                LocalTime.now().format(HEURE));
        model.addAttribute("modele", modele);
        return "vues/index";
    }

    // ModelAndView : la vue, son modèle et, si besoin, le code de la réponse, en un seul objet
    @GetMapping("/bonjour/{nom}")
    public ModelAndView bonjour(@PathVariable String nom) {
        if (nom.equals("inconnu")) {
            return new ModelAndView("vues/inconnu", Map.of("nom", nom), HttpStatus.NOT_FOUND);
        }
        PageModele modele = new PageModele(
                "Bonjour " + nom,
                "Cette fois, l'action a construit un objet ModelAndView.",
                LocalTime.now().format(HEURE));
        return new ModelAndView("vues/index", Map.of("modele", modele));
    }
}

Commentons ce code :

ligne 17 : l'annotation [@Controller] remplace l'annotation [@RestController] des exemples précédents. Avec [@RestController], ce que rend une action est la réponse (du texte, du JSON). Avec [@Controller], une action qui rend une chaîne de caractères rend le nom d'une vue : c'est la vue qui fabriquera la réponse ;
ligne 25 : l'action reçoit un paramètre de type [Model], fourni par [Spring MVC]. C'est le modèle de la vue : un dictionnaire, dont chaque entrée (un attribut) associe un nom à un objet ;
lignes 26-30 : l'action fabrique un objet [PageModele] (un titre, un message, l'heure courante) et le range dans le modèle sous le nom [modele]. C'est sous ce nom que la vue le retrouvera ;
ligne 31 : l'action rend le nom de la vue, [vues/index]. Elle ne fabrique plus la réponse : elle désigne une vue et lui a préparé ses données ;
ligne 36 : l'action [bonjour] rend un objet [ModelAndView], qui réunit en un seul objet le nom de la vue et son modèle. C'est l'autre façon d'écrire une action qui utilise une vue ;
ligne 38 : quand la vue dépend de la requête, l'action choisit la vue. Ici, le nom [inconnu] affiche la vue [vues/inconnu], avec le code 404 : le troisième argument du constructeur de [ModelAndView] est le code de la réponse. Le modèle de cette vue contient une simple chaîne, le nom demandé. [Map.of(...)] fabrique un dictionnaire non modifiable ;
ligne 44 : les deux actions partagent la même vue [vues/index], avec des modèles différents.

Où [Spring MVC] cherche-t-il la vue [vues/index] ? Il confie le nom de la vue à un résolveur de vues ([ViewResolver]), qui le transforme en une vue concrète. Celui que configure [Spring Boot] pour [Thymeleaf] ([ThymeleafViewResolver]) ajoute au nom un préfixe, [classpath:/templates/], et un suffixe, [.html] : la vue [vues/index] est le fichier [templates/vues/index.html] du classpath, c'est-à-dire des dossiers et archives où la machine virtuelle [Java] cherche les classes et les ressources de l'application. Le dossier [src/main/resources] du projet en fait partie : son contenu est copié par [Maven] dans [target/classes], à côté des classes compilées. Ces deux valeurs peuvent être changées dans [application.properties] (propriétés [spring.thymeleaf.prefix] et [spring.thymeleaf.suffix]). Contrairement à [ASP.NET Core MVC], il n'y a pas de convention qui déduirait le nom de la vue du nom du contrôleur et de l'action : l'action donne toujours le chemin de la vue, relatif au dossier [templates]. Les fichiers du projet :

13-premiere-vue/
├── src/
│   └── main/
│       ├── java/
│       │   └── exemple13/
│       │       ├── controllers/
│       │       │   └── VuesController.java
│       │       ├── models/
│       │       │   └── PageModele.java
│       │       └── Exemple13Application.java
│       └── resources/
│           ├── templates/
│           │   └── vues/
│           │       ├── inconnu.html
│           │       └── index.html
│           └── application.properties
└── pom.xml

Le fichier [templates/vues/index.html] :

<!doctype html>
<!--/* xmlns:th : déclare l'espace de noms des attributs th:... (utile aux éditeurs) */-->
<html lang="fr" xmlns:th="http://www.thymeleaf.org">
<head>
  <meta charset="utf-8">
  <title th:text="${modele.titre}">Titre de la page</title>
</head>
<body>
  <h1 th:text="${modele.titre}">Titre de la page</h1>
  <p th:text="${modele.message}">Un message.</p>
  <p>Page fabriquée à <span th:text="${modele.heure}">12:00:00</span>.</p>
</body>
</html>

Commentons ce code :

ligne 2 : un commentaire [Thymeleaf] s'écrit []. C'est un commentaire HTML dont le contenu est encadré par [/*] et [*/] : [Thymeleaf] le retire de la page produite, alors qu'un commentaire HTML ordinaire [] serait envoyé au navigateur ;
ligne 3 : l'attribut [xmlns:th] déclare l'espace de noms des attributs [th:]. Il ne sert qu'aux éditeurs de code (complétion, vérification) : [Thymeleaf] traite les attributs [th:] même sans lui, et le retire de la page produite ;
ligne 6 : l'attribut [th:text] remplace le contenu de la balise par la valeur de l'expression. [${modele.titre}] est une expression de variable : [modele] est l'attribut du modèle déposé par l'action, [.titre] appelle son accesseur [titre()]. Le texte « Titre de la page » écrit dans la balise n'est qu'un exemple, affiché si l'on ouvre le fichier directement dans un navigateur ; il disparaît de la page produite ;
lignes 9-11 : même principe pour le titre, le message et l'heure. Pour insérer une valeur au milieu d'un texte, on l'enveloppe dans une balise [<span>], qui porte l'attribut [th:text].

Les expressions [${...}] sont écrites dans le langage d'expressions de [Spring], [SpEL] ([Spring Expression Language]). [modele.titre] appelle la méthode [getTitre()] d'un [JavaBean], ou la méthode [titre()] d'un record : on écrit la même chose dans les deux cas.

Une vue [Thymeleaf] n'est pas compilée avec l'application : elle est lue et interprétée au moment où la page est demandée. Une erreur dans une vue n'est donc pas signalée à la compilation, mais à l'affichage de la page. Si l'on écrit [${modele.titr}] dans la vue, la requête échoue (code 500) et la console du serveur affiche : [Property or field 'titr' cannot be found on object of type 'exemple13.models.PageModele']. De même, un nom de vue qui ne correspond à aucun fichier provoque l'erreur [Error resolving template [vues/absente], template might not exist or might not be accessible by any of the configured Template Resolvers]. Le résultat, à l'URL http://localhost:5000/ :

Le code source de la page reçue par le navigateur ne contient plus aucune trace de [Thymeleaf] :

1	`curl http://localhost:5000/`

<!doctype html>

<html lang="fr">
<head>
  <meta charset="utf-8">
  <title>Ma première vue</title>
</head>
<body>
  <h1>Ma première vue</h1>
  <p>Cette page a été fabriquée par Thymeleaf, sur le serveur.</p>
  <p>Page fabriquée à <span>18:53:46</span>.</p>
</body>
</html>

On remarque que :

les attributs [th:text] ont disparu, remplacés par les valeurs du modèle, ainsi que l'attribut [xmlns:th] ;
le commentaire [Thymeleaf] a disparu, mais il laisse une ligne vide ;
les caractères accentués sont écrits tels quels ([première], [été]) : [Thymeleaf] n'échappe que les caractères qui ont un sens en HTML ([<], [>], [&], ["], [']). [Razor], lui, code par défaut les caractères accentués ([è] pour [è]), ce qui oblige le cours [ASP.NET Core MVC] à changer un réglage ; rien de tel ici.

L'URL http://localhost:5000/bonjour/martin affiche la même vue avec un autre modèle :

Dans le code HTML de cette page, l'apostrophe de « l'action » est devenue ['] : c'est l'un des caractères échappés par [th:text]. L'URL http://localhost:5000/bonjour/inconnu affiche une autre vue :

1	`curl -i http://localhost:5000/bonjour/inconnu`

HTTP/1.1 404
Content-Type: text/html;charset=UTF-8

<!doctype html>
<html lang="fr">
<head>
  <meta charset="utf-8">
  <title>Inconnu</title>
</head>
<body>

  <h1>Personne ne s&#39;appelle [inconnu] ici.</h1>
</body>
</html>

La réponse a bien le code 404 fixé par l'objet [ModelAndView] ([Tomcat] n'envoie que le code, sans son libellé [Not Found]). Le fichier [templates/vues/inconnu.html] :

<!doctype html>
<html lang="fr" xmlns:th="http://www.thymeleaf.org">
<head>
  <meta charset="utf-8">
  <title>Inconnu</title>
</head>
<body>
  <!--/* |...| : un texte dans lequel les expressions ${...} sont remplacées */-->
  <h1 th:text="|Personne ne s'appelle [${nom}] ici.|">Personne ne s'appelle [xx] ici.</h1>
</body>
</html>

ligne 9 : un texte encadré par deux barres verticales [|...|] est une substitution littérale : les expressions [${...}] qu'il contient sont remplacées par leur valeur. C'est plus lisible qu'une suite de [<span>]. [${nom}] est l'attribut [nom] du modèle, une simple chaîne.

4.2. Exemple 14 : le langage Thymeleaf

Une vue [Thymeleaf] ne contient pas de code [Java] : tout passe par les attributs [th:] et par les expressions qu'ils contiennent. On y trouve pourtant des conditions, des boucles, des variables locales, des appels de méthodes. Cette puissance demande de la discipline : la vue doit rester une mise en forme ; les calculs et les décisions appartiennent à l'action et aux services. L'exemple 14 fait le tour de la syntaxe. Le modèle, fichier [models/BasesModele.java] :

package exemple14.models;

import java.math.BigDecimal;
import java.util.List;

public record BasesModele(
        String titre,
        String nom,
        String surnom,
        String html,
        boolean connecte,
        String devise,
        List<Produit> produits,
        List<Produit> panier,
        Adresse adresse) {

    public record Produit(String nom, BigDecimal prix, boolean enStock) {
    }

    public record Adresse(String rue, String ville) {
    }
}

lignes 6-15 : le modèle est un record : quelques chaînes, un booléen, deux listes de produits et une adresse ;
lignes 17-21 : deux records imbriqués dans le premier : [BasesModele.Produit] et [BasesModele.Adresse]. Un prix est un [BigDecimal], le type [Java] des nombres décimaux exacts (un [double] ne sait pas représenter exactement [0.1]).

Le fichier [controllers/BasesController.java] :

package exemple14.controllers;

import java.math.BigDecimal;
import java.util.List;

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

import exemple14.models.BasesModele;
import exemple14.models.BasesModele.Adresse;
import exemple14.models.BasesModele.Produit;

@Controller
public class BasesController {

    @GetMapping("/")
    public String index(Model model) {
        BasesModele modele = new BasesModele(
                "Les bases de Thymeleaf",
                "Martin",
                null,
                "<b>ceci est du HTML</b>",
                true,
                "€",
                List.of(
                        new Produit("Clavier", new BigDecimal("25"), true),
                        new Produit("Souris", new BigDecimal("12.5"), false),
                        new Produit("Écran", new BigDecimal("149"), true)),
                List.of(),
                new Adresse("12 rue des Lilas", "Angers"));
        model.addAttribute("modele", modele);
        return "bases/index";
    }
}

lignes 19-31 : l'action remplit le modèle : quelques chaînes, un booléen, une liste de trois produits, un panier vide et une adresse. Le surnom (ligne 22) est volontairement [null]. [List.of(...)] fabrique une liste non modifiable ; [List.of()] une liste vide.

La vue, fichier [templates/bases/index.html] :

<!doctype html>
<html lang="fr" xmlns:th="http://www.thymeleaf.org">
<head>
  <meta charset="utf-8">
  <title th:text="${modele.titre}">Titre</title>
</head>
<!--/* th:with : des variables locales, utilisables dans la balise et ses descendantes */-->
<body th:with="total=${#aggregates.sum(modele.produits.![prix])}, nombre=${#lists.size(modele.produits)}">
  <h1 th:text="${modele.titre}">Titre</h1>
  <!--/* 1. afficher une valeur du modèle ; null n'affiche rien. Ce commentaire
         Thymeleaf, lui, n'apparaît pas dans la page produite */-->
  <p>1. Nom : <span th:text="${modele.nom}">nom</span> - surnom : [<span th:text="${modele.surnom}">surnom</span>]</p>
  <!--/* 2. th:text échappe le HTML, th:utext l'insère tel quel */-->
  <p>2a. <span th:text="${modele.html}">html</span></p>
  <p>2b. <span th:utext="${modele.html}">html</span></p>
  <!--/* 3. une condition : th:if affiche la balise si la condition est vraie, th:unless si elle est fausse */-->
  <p th:if="${modele.connecte}">3. Vous êtes connecté.</p>
  <p th:unless="${modele.connecte}">3. Vous n'êtes pas connecté.</p>
  <!--/* 4. une boucle : la balise qui porte th:each est répétée ; stat : l'état de la boucle */-->
  <p>4. Nos produits :</p>
  <ul>
    <li th:each="produit, stat : ${modele.produits}">n° [[${stat.index}]] : [[${produit.nom}]], [[${produit.prix}]] [[${modele.devise}]]
      <span th:text="${produit.enStock} ? '(en stock)' : '(épuisé)'">(en stock)</span>
      <th:block th:if="${stat.first}">- le premier</th:block>
      <th:block th:if="${stat.last}">- le dernier, vu par [[${modele.nom}]]</th:block>
    </li>
  </ul>
  <!--/* 5. la liste vide */-->
  <p>5. Votre panier :
    <th:block th:if="${#lists.isEmpty(modele.panier)}">il est vide.</th:block>
    <span th:each="p : ${modele.panier}" th:text="${p.nom}">produit</span>
  </p>
  <!--/* 6. des expressions calculées, les variables de th:with, et un utilitaire (#numbers) */-->
  <p th:text="|6. ${nombre} produits, pour un total de ${total} ${modele.devise} ; prix moyen : ${#numbers.formatDecimal(total.doubleValue() / nombre, 1, 2)} ${modele.devise}|">6.</p>
  <p>7. Adresse : [[${modele.adresse.rue}]], [[${#strings.toUpperCase(modele.adresse.ville)}]]</p>
  <p>8. Une adresse électronique : contact@exemple.fr</p>
</body>
</html>

Commentons ce code :

ligne 8 : l'attribut [th:with] déclare des variables locales, utilisables dans la balise qui le porte et dans toutes ses descendantes : ici [total] et [nombre], dans tout le corps de la page. [modele.produits.![prix]] est une projection [SpEL] : la liste des prix des produits. [#aggregates] et [#lists] sont des objets utilitaires de [Thymeleaf] (ils commencent par [#]) : [#aggregates.sum] fait la somme d'une liste de nombres, [#lists.size] compte les éléments d'une liste ;
lignes 10-11 : un commentaire [Thymeleaf], absent de la page produite ;
ligne 12 : une valeur [null] ([${modele.surnom}]) n'affiche rien, sans erreur ;
lignes 14-15 : [th:text] échappe les caractères spéciaux du HTML ([<] devient [<]...) : le texte s'affiche tel quel. [th:utext] ([unescaped text]) l'insère sans échappement : il est interprété comme du HTML. On n'utilise [th:utext] que pour du HTML fabriqué par l'application, jamais pour une donnée saisie par un utilisateur : celui-ci pourrait injecter du HTML, voire du [JavaScript], dans la page (attaque dite [XSS], [cross-site scripting]) ;
lignes 17-18 : une condition. [th:if] garde la balise (et son contenu) si l'expression est vraie, et la supprime sinon ; [th:unless] fait l'inverse. Il n'y a pas de [th:else] : on écrit la condition contraire ;
ligne 22 : une boucle. L'attribut [th:each] répète la balise qui le porte, ici [<li>], une fois par élément de la liste. [produit] est l'élément courant ; [stat], facultatif, est l'état de l'itération : [stat.index] (à partir de 0), [stat.count] (à partir de 1), [stat.size], [stat.first], [stat.last], [stat.even], [stat.odd]. Dans le texte de la balise, [[[${produit.nom}]]] est une expression en ligne : elle insère la valeur, échappée comme avec [th:text], sans balise [<span>] (la forme [[(...)]] insère sans échappement, comme [th:utext]) ;
ligne 23 : l'opérateur conditionnel [condition ? valeur1 : valeur2]. Les chaînes littérales s'écrivent entre apostrophes ;
lignes 24-25 : [th:block] est une balise propre à [Thymeleaf] : elle ne sert qu'à porter des attributs [th:] et disparaît de la page produite, en ne laissant que son contenu. [stat.first] et [stat.last] testent la position dans la boucle ;
lignes 30-31 : le cas de la liste vide. [#lists.isEmpty] teste si la liste est vide ; une boucle [th:each] sur une liste vide ne produit rien ;
ligne 34 : une substitution littérale [|...|] qui utilise les variables de [th:with], et deux appels de méthodes : [total.doubleValue()] convertit le [BigDecimal] en [double], et [#numbers.formatDecimal(valeur, 1, 2)] formate un nombre avec au moins un chiffre avant la virgule et exactement deux après ;
ligne 35 : un chemin pointé [modele.adresse.rue], et l'objet utilitaire [#strings], qui regroupe les opérations sur les chaînes ([toUpperCase], [isEmpty], [contains], [startsWith]...) ;
ligne 36 : [Thymeleaf] ne traite que les attributs [th:] et les expressions en ligne [[[...]]] : le reste du texte est recopié tel quel. Le caractère [@] n'a ici aucun sens particulier.

Le résultat, à l'URL http://localhost:5000/ :

Le code HTML produit :

1	`curl http://localhost:5000/`

<!doctype html>
<html lang="fr">
<head>
  <meta charset="utf-8">
  <title>Les bases de Thymeleaf</title>
</head>

<body>
  <h1>Les bases de Thymeleaf</h1>

  <p>1. Nom : <span>Martin</span> - surnom : [<span></span>]</p>

  <p>2a. <span>&lt;b&gt;ceci est du HTML&lt;/b&gt;</span></p>
  <p>2b. <span><b>ceci est du HTML</b></span></p>

  <p>3. Vous êtes connecté.</p>


  <p>4. Nos produits :</p>
  <ul>
    <li>n° 0 : Clavier, 25 €
      <span>(en stock)</span>
      - le premier

    </li>
    <li>n° 1 : Souris, 12.5 €
      <span>(épuisé)</span>


    </li>
    <li>n° 2 : Écran, 149 €
      <span>(en stock)</span>

      - le dernier, vu par Martin
    </li>
  </ul>

  <p>5. Votre panier :
    il est vide.

  </p>

  <p>6. 3 produits, pour un total de 186.5 € ; prix moyen : 62.17 €</p>
  <p>7. Adresse : 12 rue des Lilas, ANGERS</p>
  <p>8. Une adresse électronique : contact@exemple.fr</p>
</body>
</html>

On remarque que :

les balises [th:block], les commentaires [Thymeleaf] et les balises supprimées par [th:if] / [th:unless] laissent des lignes blanches, sans effet sur l'affichage ;
le prix moyen est [62.17] pour [curl], [62,17] dans le navigateur. [#numbers.formatDecimal] utilise la langue de la requête. Par défaut, [Spring MVC] la lit dans l'entête HTTP [Accept-Language] envoyé par le navigateur : un navigateur réglé en français envoie [Accept-Language: fr-FR] et obtient une virgule ; [curl] n'envoie pas cet entête, et la langue est alors celle du système sur lequel tourne le serveur (ici l'anglais ; sur un poste réglé en français, [curl] obtiendrait lui aussi une virgule). L'exemple 16 et le chapitre « Internationalisation » reviennent sur ce mécanisme ;
les prix eux-mêmes ([12.5]) sont écrits par la méthode [toString] de [BigDecimal], qui ne dépend pas de la langue. L'exemple 16 les met en forme.

Pour conclure cet exemple, voici les cinq sortes d'expressions de [Thymeleaf], dont les exemples de ce chapitre et du suivant se serviront :

Expression	Rôle	Exemple
[${...}]	expression de variable ([SpEL]) : un attribut du modèle, une propriété, un appel de méthode, un bean ([${@nom...}]), un objet utilitaire ([${#strings...}])	13, 14, 16
*[{...}]**	expression de sélection : une propriété de l'objet désigné par l'attribut [th:object]	18, 19, 21
[#{...}]	message : un texte du fichier [messages.properties], dans la langue de la requête	chapitre suivant
[@{...}]	lien : une URL, avec ses variables et ses paramètres	16, 21
[~{...}]	fragment : un morceau de page à insérer	15 à 21

Les objets utilitaires, eux, sont nombreux : [#strings], [#numbers], [#lists], [#aggregates], [#dates] (dates [java.util.Date]), [#temporals] (dates [java.time] : [LocalDate], [LocalDateTime]...), [#locale] (la langue de la requête), [#ids] et [#fields] (formulaires, exemples 18 et 19)... La documentation de [Thymeleaf] (https://www.thymeleaf.org) les décrit tous.

4.3. Exemple 15 : gabarit, fragments, fichiers statiques

Les pages d'un site partagent un gabarit commun (entête, barre de navigation, pied de page). Les morceaux de page réutilisables sont, pour [Thymeleaf], des fragments ; et le gabarit lui-même est un fragment, dans lequel chaque page insère son contenu. Enfin, les pages ont besoin de fichiers statiques (feuilles de style, images, scripts), servis tels quels, sans passer par un contrôleur. Les fichiers de l'exemple :

15-gabarit/
├── src/
│   └── main/
│       ├── java/
│       │   └── exemple15/
│       │       ├── config/
│       │       │   ├── ModeleCommun.java
│       │       │   └── WebConfig.java
│       │       ├── controllers/
│       │       │   └── PagesController.java
│       │       └── Exemple15Application.java
│       └── resources/
│           ├── static/
│           │   └── css/
│           │       └── styles.css
│           ├── templates/
│           │   ├── fragments/
│           │   │   ├── carte.html
│           │   │   └── navbar.html
│           │   ├── pages/
│           │   │   ├── accueil.html
│           │   │   ├── brute.html
│           │   │   └── equipe.html
│           │   └── layout.html
│           └── application.properties
└── pom.xml

4.3.1. Les fichiers statiques

[Spring Boot] sert automatiquement, sans contrôleur, les fichiers du dossier [static] des ressources : le fichier [src/main/resources/static/css/styles.css] est servi à l'URL [/css/styles.css]. Si aucun fichier ne correspond à l'URL, et qu'aucune action ne la traite, la réponse est une 404. Vérifions :

1	`curl -i http://localhost:5000/css/styles.css`

HTTP/1.1 200
Last-Modified: Fri, 25 Sep 2026 16:02:53 GMT
Accept-Ranges: bytes
Content-Type: text/css
Content-Length: 422

/* quelques réglages en plus de Bootstrap */
body {
  background-color: #f5f7fa;
}

/* le pied de page du gabarit */
.pied {
  margin-top: 2rem;
  font-size: 0.85rem;
  color: #6c757d;
}

/* les messages d'erreur, en bas de page, sur fond rose léger */
.zone-erreur {
  margin-top: 1.5rem;
  padding: 0.75rem 1rem;
  background-color: #fdecef;
  border: 1px solid #f5c2c7;
  border-radius: 0.375rem;
  color: #842029;
}

L'entête [Last-Modified] donne la date de modification du fichier : le navigateur pourra la renvoyer pour demander le fichier seulement s'il a changé.

Le framework CSS [Bootstrap] est commun à tous les exemples : il est rangé une seule fois, dans le dossier [exemples/commun/bootstrap], hors des ressources des exemples. Il faut donc dire à [Spring MVC] où le trouver. Le fichier [config/WebConfig.java] :

package exemple15.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

// la configuration de Spring MVC, complétée
@Configuration
public class WebConfig implements WebMvcConfigurer {

    // Bootstrap, partagé par les exemples : le dossier exemples/commun/bootstrap
    // est servi sous l'URL /bootstrap/...
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/bootstrap/**")
                // "file:" : un dossier du disque, relatif au dossier courant. Deux
                // essais : lancé depuis le dossier de l'exemple, ou depuis [exemples]
                .addResourceLocations("file:../commun/bootstrap/", "file:commun/bootstrap/");
    }
}

Commentons ce code :

ligne 8 : une classe de configuration (cf. exemple 06) ;
ligne 9 : l'interface [WebMvcConfigurer] permet de compléter la configuration de [Spring MVC] faite par [Spring Boot], sans la remplacer : on redéfinit seulement les méthodes qui nous intéressent (toutes les autres ont une implémentation par défaut, vide) ;
lignes 14-19 : la méthode [addResourceHandlers] déclare des dossiers de fichiers statiques. Les URL qui commencent par [/bootstrap/] (ligne 15 ; [**] désigne n'importe quelle suite de dossiers et de fichiers) sont servies à partir du dossier [commun/bootstrap] ;
ligne 18 : le préfixe [file:] désigne un dossier du disque (et non du classpath). Le chemin est relatif au dossier courant, celui depuis lequel l'application a été lancée : [../commun/bootstrap/] si on la lance depuis le dossier de l'exemple, [commun/bootstrap/] si on la lance depuis le dossier [exemples]. Les deux emplacements sont essayés dans l'ordre. Ainsi, [exemples/commun/bootstrap/css/bootstrap.min.css] est servi à l'URL [/bootstrap/css/bootstrap.min.css]. L'étude de cas, elle, range [Bootstrap] dans son propre dossier [static].

Tous les exemples suivants ont ce fichier [WebConfig.java].

4.3.2. Le gabarit

Le fichier [templates/layout.html] :

<!doctype html>
<!--/* le gabarit des pages : un fragment qui a deux paramètres, le titre de la
       page et son contenu (lui-même un fragment, fourni par la page) */-->
<html lang="fr" xmlns:th="http://www.thymeleaf.org" th:fragment="page(titre, contenu)">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title th:text="|${titre} - Mon site|">Mon site</title>
  <link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-3">
    <!--/* insertion du fragment [navbar] du fichier fragments/navbar.html */-->
    <nav th:replace="~{fragments/navbar :: navbar}"></nav>
    <!--/* le contenu de la page demandée par l'action est inséré ici */-->
    <main th:replace="${contenu}"></main>
    <!--/* chemin : ajouté au modèle de toutes les vues (cf. config/ModeleCommun.java) */-->
    <footer class="pied" th:text="|Page [${chemin}] - © ${#dates.year(#dates.createNow())}|">pied de page</footer>
  </div>
</body>
</html>

Commentons ce code :

ligne 4 : l'attribut [th:fragment] fait de la balise [<html>], et donc de toute la page, un fragment nommé [page], qui attend deux paramètres : [titre] et [contenu]. Les pages de l'application appelleront ce fragment en lui passant leur titre et leur contenu ;
ligne 8 : le paramètre [titre] s'utilise comme un attribut du modèle ;
lignes 9-10 : les feuilles de style, servies comme fichiers statiques ;
ligne 15 : l'attribut [th:replace] remplace la balise qui le porte (ici [<nav>]) par un fragment. [~{fragments/navbar :: navbar}] est une expression de fragment : le fragment [navbar] du fichier [templates/fragments/navbar.html] (à gauche de [::], le nom de la vue ; à droite, le nom du fragment) ;
ligne 17 : l'emplacement où est inséré le contenu de la page, reçu dans le paramètre [contenu] : ce paramètre est lui-même un fragment, que [th:replace] insère à la place de la balise [<main>] ;
ligne 19 : [chemin] est le chemin de la page demandée. Ce n'est pas un paramètre du fragment : c'est un attribut ajouté au modèle de toutes les vues, par une classe que nous verrons plus loin. [#dates.createNow()] est la date courante, et [#dates.year] en extrait l'année.

Il existe un second attribut d'insertion, [th:insert], qui insère le fragment à l'intérieur de la balise hôte, au lieu de la remplacer. Avec un fragment [<span th:fragment="f">...</span>], l'écriture [<div th:replace="~{:: f}"></div>] produit [<span>...</span>], et [<div th:insert="~{:: f}"></div>] produit [<div><span>...</span></div>] ([~{:: f}], sans nom de vue, désigne un fragment de la vue courante). Les exemples de ce cours utilisent [th:replace].

Le fichier [templates/fragments/navbar.html] :

<!--/* un fichier de fragments : chaque balise th:fragment est un morceau de page réutilisable */-->
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3" th:fragment="navbar">
  <span class="navbar-brand">Mon site</span>
  <div class="navbar-nav">
    <a class="nav-link" href="/">Accueil</a>
    <a class="nav-link" href="/equipe">Équipe</a>
    <a class="nav-link" href="/brute">Page sans gabarit</a>
  </div>
</nav>

ligne 2 : un fichier de fragments n'est pas une page complète : il contient une ou plusieurs balises qui portent un attribut [th:fragment]. Ce fragment-ci n'a pas de paramètres. On remarque que le fichier ne déclare pas l'espace de noms [xmlns:th] : ce n'est pas nécessaire.

Le fichier [templates/fragments/carte.html] :

<!--/* une "carte" Bootstrap ; ses deux paramètres : un nom et une fonction */-->
<div class="card" th:fragment="carte(nom, fonction)">
  <div class="card-body">
    <h5 class="card-title" th:text="${nom}">Nom</h5>
    <p class="card-text" th:text="${fonction}">Fonction</p>
  </div>
</div>

ligne 2 : le fragment [carte] a deux paramètres, un nom et une fonction ;
lignes 4-5 : les paramètres s'utilisent comme des attributs du modèle.

4.3.3. Les pages

Le fichier [controllers/PagesController.java] :

package exemple15.controllers;

import java.util.List;

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

@Controller
public class PagesController {

    // un membre de l'équipe
    public record Membre(String nom, String fonction) {
    }

    @GetMapping("/")
    public String accueil() {
        return "pages/accueil";
    }

    @GetMapping("/equipe")
    public String equipe(Model model) {
        List<Membre> membres = List.of(
                new Membre("Marie Pélissier", "Directrice"),
                new Membre("Jacques Bromard", "Développeur"),
                new Membre("Philippe Jandot", "Graphiste"));
        model.addAttribute("membres", membres);
        return "pages/equipe";
    }

    @GetMapping("/brute")
    public String brute() {
        return "pages/brute";
    }
}

lignes 13-14 : le type des membres de l'équipe, un record déclaré dans le contrôleur ([PagesController.Membre]) ;
lignes 17-19 : l'action [accueil] n'a pas de modèle : elle n'a pas besoin du paramètre [Model] ;
lignes 22-28 : l'action [equipe] transmet une liste de membres.

Le fichier [templates/pages/accueil.html] :

<!doctype html>
<!--/* toute la page est REMPLACÉE par le fragment [page] du gabarit, auquel on
       passe le titre et le fragment [main] de cette page (~{::main}) */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page('Accueil', ~{::main})}">
<body>
<main>
  <h1>Bienvenue</h1>
  <p>Cette page ne contient que son propre contenu : l'entête, la barre de
    navigation et le pied de page viennent du gabarit <code>layout.html</code>.</p>
  <!--/* le fragment [carte], avec deux paramètres écrits sur place */-->
  <div th:replace="~{fragments/carte :: carte('Un fragment', 'inséré avec des paramètres écrits sur place')}"></div>
</main>
</body>
</html>

Commentons ce code :

ligne 4 : l'attribut [th:replace] de la balise [<html>] remplace toute la page par le fragment [page] du gabarit [layout.html]. Il lui passe deux paramètres : le titre, une chaîne littérale écrite entre apostrophes, et le contenu, [~{::main}]. Cette expression de fragment, sans nom de vue, désigne une balise de la vue courante : ici la balise [<main>] (lignes 6-12). Le gabarit est ainsi produit, avec, à la place de sa propre balise [<main>], celle de la page ;
ligne 11 : l'appel du fragment [carte], avec deux paramètres écrits sur place.

Tout ce qui, dans la page, n'est pas dans la balise [<main>] (la balise [<body>], par exemple) disparaît : seul compte le fragment transmis au gabarit. Les balises [<html>] et [<body>] ne sont là que pour que le fichier reste une page HTML valide, que l'on peut ouvrir dans un navigateur.

Le fichier [templates/pages/equipe.html] :

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page('Notre équipe', ~{::main})}">
<body>
<main>
  <h1>Notre équipe</h1>
  <div class="row g-3">
    <div class="col-md-4" th:each="membre : ${membres}">
      <!--/* le fragment reçoit le nom et la fonction du membre courant */-->
      <div th:replace="~{fragments/carte :: carte(${membre.nom}, ${membre.fonction})}"></div>
    </div>
  </div>
</main>
</body>
</html>

ligne 7 : la balise [<div class="col-md-4">] est répétée pour chaque membre ;
ligne 9 : le fragment reçoit le nom et la fonction du membre courant : la balise qui porte [th:replace] est à l'intérieur de celle qui porte [th:each], où la variable [membre] est définie.

Le fichier [templates/pages/brute.html] :

<!doctype html>
<!--/* cette vue n'utilise pas le gabarit : c'est une page complète */-->
<html lang="fr">
<head>
  <meta charset="utf-8">
  <title>Page brute</title>
</head>
<body>
  <p>Cette page n'utilise pas le gabarit : ni Bootstrap, ni barre de navigation.</p>
  <p><a href="/">Retour à l'accueil</a></p>
</body>
</html>

lignes 3-11 : cette vue n'appelle pas le gabarit : c'est une page complète, sans aucun attribut [th:]. [Thymeleaf] la recopie telle quelle (sauf le commentaire de la ligne 2). Rien n'oblige une vue à utiliser le gabarit.

Le code HTML de la page http://localhost:5000/equipe montre le résultat de l'assemblage :

1	`curl http://localhost:5000/equipe`

<!doctype html>
<html lang="fr">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Notre équipe - Mon site</title>
  <link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-3">

    <nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <span class="navbar-brand">Mon site</span>
  <div class="navbar-nav">
    <a class="nav-link" href="/">Accueil</a>
    <a class="nav-link" href="/equipe">Équipe</a>
    <a class="nav-link" href="/brute">Page sans gabarit</a>
  </div>
</nav>

    <main>
  <h1>Notre équipe</h1>
  <div class="row g-3">
    <div class="col-md-4">

      <div class="card">
  <div class="card-body">
    <h5 class="card-title">Marie Pélissier</h5>
    <p class="card-text">Directrice</p>
  </div>
</div>
    </div>
    <div class="col-md-4">

      <div class="card">
  <div class="card-body">
    <h5 class="card-title">Jacques Bromard</h5>
    <p class="card-text">Développeur</p>
  </div>
</div>
    </div>
    <div class="col-md-4">

      <div class="card">
  <div class="card-body">
    <h5 class="card-title">Philippe Jandot</h5>
    <p class="card-text">Graphiste</p>
  </div>
</div>
    </div>
  </div>
</main>

    <footer class="pied">Page [/equipe] - © 2026</footer>
  </div>
</body>
</html>

Le titre, la barre de navigation, les trois cartes et le pied de page ont été assemblés à partir de quatre fichiers : [layout.html], [navbar.html], [equipe.html] et [carte.html].

4.3.4. Un attribut commun à toutes les vues

Le pied de page du gabarit affiche le chemin de la page demandée, [chemin]. Avec [Razor], une vue a directement accès à la requête en cours. Une vue [Thymeleaf] le pouvait aussi, jusqu'à la version 3.0, par l'objet [#request] : on aurait écrit [${#request.requestURI}]. Ce n'est plus le cas depuis la version 3.1. Une vue qui utilise [#request] provoque une erreur 500, et la console affiche :

java.lang.IllegalArgumentException: The 'request','session','servletContext' and 'response' expression utility objects are no longer available by default for template expressions and their use is not recommended. In cases where they are really needed, they should be manually added as context variables.

Les objets [#request], [#session], [#servletContext] et [#response] ont été retirés : ils permettaient à une vue de lire n'importe quel paramètre de la requête, ce qui ouvrait la porte à des injections, et ils liaient [Thymeleaf] à l'API des servlets. L'écriture [${#ctx.request.requestURI}] ne marche pas non plus : [#ctx.request] vaut [null]. Le message d'erreur donne la solution : ajouter au modèle ce dont la vue a besoin. Pour que cela vaille pour toutes les vues, sans que chaque action ait à le faire, on écrit le fichier [config/ModeleCommun.java] :

package exemple15.config;

import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ModelAttribute;

import jakarta.servlet.http.HttpServletRequest;

// @ControllerAdvice : cette classe complète TOUS les contrôleurs de l'application
@ControllerAdvice
public class ModeleCommun {

    // @ModelAttribute : exécutée avant chaque action, cette méthode ajoute au
    // modèle de toutes les vues l'attribut [chemin], le chemin de la page demandée
    @ModelAttribute("chemin")
    public String chemin(HttpServletRequest request) {
        return request.getRequestURI();
    }
}

Commentons ce code :

ligne 9 : l'annotation [@ControllerAdvice] désigne une classe qui complète tous les contrôleurs de l'application. Ce qu'elle déclare s'applique à chacun d'eux, comme si c'était écrit dans chacun ;
ligne 14 : une méthode annotée par [@ModelAttribute("chemin")] est exécutée avant chaque action ; ce qu'elle rend est ajouté au modèle sous le nom [chemin]. Écrite dans un contrôleur, elle concerne les actions de ce contrôleur (cf. exemple 18) ; écrite dans une classe [@ControllerAdvice], elle concerne toutes les actions de l'application ;
lignes 15-16 : la méthode peut recevoir les mêmes paramètres qu'une action : ici la requête en cours, [HttpServletRequest] (cf. exemple 05). [getRequestURI()] rend le chemin demandé, sans les paramètres.

L'étude de cas utilise le même procédé (son fichier [web/ModeleCommun.java]) pour fournir à toutes ses vues le chemin, la langue et l'utilisateur connecté.

Les pages obtenues, aux URL http://localhost:5000/, http://localhost:5000/equipe et http://localhost:5000/brute :

Le gabarit, les fragments et l'attribut commun [chemin] sont exactement ce qu'utilise l'étude de cas : un gabarit [layout.html], des fragments pour la barre de navigation, les messages, les fenêtres de confirmation.

4.4. Exemple 16 : les helpers

Une vue a souvent besoin de petites fonctions de mise en forme : formater une date ou un prix, mettre un texte en majuscules, fabriquer un badge HTML... On les appelle des helpers (des aides). Avec [Thymeleaf], ce sont des méthodes de beans [Spring], appelées dans une expression, ou des fragments. [Thymeleaf] permet en outre de créer ses propres attributs, rassemblés dans un dialecte.

4.4.1. Un bean appelé par les vues

Le fichier [aides/Formats.java] :

package exemple16.aides;

import java.math.BigDecimal;
import java.text.NumberFormat;
import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.time.format.FormatStyle;
import java.util.Currency;
import java.util.Locale;

import org.springframework.context.i18n.LocaleContextHolder;
import org.springframework.stereotype.Component;

// @Component("formats") : un bean nommé [formats], que les vues appellent
// par ${@formats.monnaie(...)}
@Component("formats")
public class Formats {

    // "clavier" -> "CLAVIER" ; Locale.ROOT : le résultat ne dépend pas de la langue
    public String majuscules(String texte) {
        return texte == null ? "" : texte.toUpperCase(Locale.ROOT);
    }

    // un montant dans une devise, au format de la langue de la requête
    public String monnaie(BigDecimal montant, String devise) {
        // la langue de la requête en cours, fixée par le LocaleResolver (cf. WebConfig)
        Locale langue = LocaleContextHolder.getLocale();
        NumberFormat format = NumberFormat.getCurrencyInstance(langue);
        format.setCurrency(Currency.getInstance(devise));
        return format.format(montant);
    }

    // la même, en euros
    public String monnaie(BigDecimal montant) {
        return monnaie(montant, "EUR");
    }

    // une date en toutes lettres, dans la langue de la requête : "vendredi 25 septembre 2026"
    public String date(LocalDate jour) {
        return jour.format(DateTimeFormatter.ofLocalizedDate(FormatStyle.FULL).withLocale(LocaleContextHolder.getLocale()));
    }
}

Commentons ce code :

ligne 16 : l'annotation [@Component] fait de la classe un bean : [Spring] la trouve au démarrage (comme il trouve les contrôleurs), en crée une instance et la garde. ["formats"] est le nom du bean : c'est sous ce nom que les vues l'appelleront ;
lignes 20-22 : la mise en majuscules. [Locale.ROOT] rend le résultat indépendant de la langue de l'utilisateur ;
lignes 25-31 : un montant dans une devise, au format de la langue de la requête. [LocaleContextHolder.getLocale()] (ligne 27) rend cette langue, un objet [Locale] fixé par [Spring MVC] au début de chaque requête. [NumberFormat.getCurrencyInstance] fournit le format monétaire de cette langue : séparateur décimal, séparateur des milliers, place du symbole ; [setCurrency] choisit la devise, désignée par son code international ([EUR], [USD]) ;
lignes 34-36 : une surcharge de la méthode : même nom, autres paramètres. Sans devise, c'est l'euro ;
lignes 39-41 : une date en toutes lettres ([FormatStyle.FULL]), dans la langue de la requête.

La page [templates/pages/produits.html] appelle ces méthodes :

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page('Produits', ~{::main})}">
<body>
<main>
  <h1>Produits</h1>
  <table class="table table-sm w-auto">
    <thead><tr><th>Produit</th><th>Prix</th><th>Prix en dollars</th><th>Stock</th></tr></thead>
    <tbody>
      <tr th:each="produit : ${produits}">
        <td th:text="${@formats.majuscules(produit.nom)}">CLAVIER</td>
        <td th:text="${@formats.monnaie(produit.prix)}">25,00 €</td>
        <td th:text="${@formats.monnaie(produit.prix, 'USD')}">25,00 $US</td>
        <!--/* le fragment [badge] fabrique le HTML du badge */-->
        <td><span th:replace="~{fragments/badge :: badge(${produit.stock})}">badge</span></td>
      </tr>
    </tbody>
  </table>
</main>
</body>
</html>

lignes 10-12 : dans une expression [${...}], la notation [@formats] désigne le bean de nom [formats] : [${@formats.monnaie(produit.prix)}] appelle sa méthode [monnaie]. Ce que rend la méthode est inséré par [th:text], donc échappé ;
ligne 14 : le badge est fabriqué par un fragment, décrit ci-dessous.

Le fichier [templates/fragments/badge.html] :

<!--/* un badge Bootstrap : vert si le produit est en stock, rouge sinon.
       Un fragment est la façon Thymeleaf de fabriquer un morceau de HTML réutilisable */-->
<span class="badge" th:fragment="badge(stock)"
      th:classappend="${stock > 0} ? 'text-bg-success' : 'text-bg-danger'"
      th:text="${stock > 0} ? |${stock} en stock| : 'épuisé'">12 en stock</span>

ligne 3 : un helper qui fabrique du HTML est, avec [Thymeleaf], un fragment : ici une balise [<span>] qui reçoit en paramètre le stock du produit ;
ligne 4 : l'attribut [th:classappend] ajoute une classe CSS à celles de la balise ([badge]) : verte ([text-bg-success]) si le produit est en stock, rouge sinon ;
ligne 5 : le texte du badge, échappé par [th:text]. Contrairement à un helper qui fabriquerait du HTML dans une chaîne de caractères, un fragment n'a pas à se soucier de l'échappement : [th:text] s'en charge.

Le contrôleur, fichier [controllers/PagesController.java] :

package exemple16.controllers;

import java.math.BigDecimal;
import java.time.LocalDate;
import java.util.List;

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

@Controller
public class PagesController {

    public record Produit(String nom, BigDecimal prix, int stock) {
    }

    @GetMapping("/")
    public String accueil(Model model) {
        model.addAttribute("aujourdhui", LocalDate.now());
        return "pages/accueil";
    }

    @GetMapping("/produits")
    public String produits(Model model) {
        model.addAttribute("produits", List.of(
                new Produit("clavier", new BigDecimal("25"), 12),
                new Produit("souris", new BigDecimal("12.5"), 0),
                new Produit("écran", new BigDecimal("1149.9"), 3)));
        return "pages/produits";
    }
}

ligne 19 : la page d'accueil reçoit la date du jour, un [LocalDate] (une date sans heure) ;
lignes 25-28 : la liste des produits.

Le fichier [templates/pages/accueil.html] :

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page('Accueil', ~{::main})}">
<body>
<main>
  <h1>Accueil</h1>
  <!--/* @formats : le bean de nom [formats] ; on appelle sa méthode date */-->
  <p th:text="|Nous sommes le ${@formats.date(aujourdhui)}.|">Nous sommes le...</p>
  <!--/* #locale : la langue de la requête */-->
  <p>Langue de formatage : <span th:text="${#locale}">fr_FR</span>
    (<a href="/?lang=en">en anglais</a>, <a href="/">en français</a>)</p>
</main>
</body>
</html>

ligne 7 : l'appel de la méthode [date] du bean [formats], dans une substitution littérale ;
ligne 9 : l'objet utilitaire [#locale] est la langue de la requête.

4.4.2. La langue de la requête

Qui fixe la langue de la requête ? Un bean de [Spring MVC], le résolveur de langue ([LocaleResolver]). Celui que [Spring Boot] installe par défaut, [AcceptHeaderLocaleResolver], lit l'entête [Accept-Language] envoyé par le navigateur : c'est lui qui donnait des résultats différents au navigateur et à [curl] dans l'exemple 14. Pour pouvoir tester les deux langues facilement, l'exemple 16 le remplace par un résolveur qui lit le paramètre [lang] de l'URL. Le fichier [config/WebConfig.java] :

package exemple16.config;

import java.util.Locale;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.LocaleResolver;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

import exemple16.aides.ActifDialect;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

// la configuration de Spring MVC, complétée
@Configuration
public class WebConfig implements WebMvcConfigurer {

    // Bootstrap, partagé par les exemples : le dossier exemples/commun/bootstrap
    // est servi sous l'URL /bootstrap/...
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/bootstrap/**")
                // "file:" : un dossier du disque, relatif au dossier courant. Deux
                // essais : lancé depuis le dossier de l'exemple, ou depuis [exemples]
                .addResourceLocations("file:../commun/bootstrap/", "file:commun/bootstrap/");
    }

    // notre dialecte Thymeleaf (l'attribut ex:actif), ajouté au moteur de vues
    @Bean
    public ActifDialect actifDialect() {
        return new ActifDialect();
    }

    // la langue de formatage de chaque requête : le paramètre ?lang=en de l'URL,
    // le français sinon. Le bean doit s'appeler [localeResolver] : c'est sous ce
    // nom que Spring MVC le cherche.
    @Bean
    public LocaleResolver localeResolver() {
        return new LangueParametreResolver();
    }

    // un LocaleResolver fixe la langue (Locale) de chaque requête ; Spring la range
    // dans LocaleContextHolder, où les vues et les helpers la retrouvent
    static class LangueParametreResolver implements LocaleResolver {

        @Override
        public Locale resolveLocale(HttpServletRequest request) {
            return "en".equals(request.getParameter("lang")) ? Locale.US : Locale.FRANCE;
        }

        @Override
        public void setLocale(HttpServletRequest request, HttpServletResponse response, Locale locale) {
            throw new UnsupportedOperationException("la langue est fixée par l'URL");
        }
    }
}

Commentons ce code :

lignes 21-27 : les fichiers de [Bootstrap], comme dans l'exemple 15 ;
lignes 30-33 : notre dialecte [Thymeleaf], décrit plus loin, déclaré comme bean. [Spring Boot] ajoute automatiquement au moteur [Thymeleaf] tous les beans qui sont des dialectes ;
lignes 38-41 : notre résolveur de langue. Le bean doit s'appeler [localeResolver] : c'est sous ce nom que [Spring MVC] le cherche. Une méthode [@Bean] donne son nom au bean : [localeResolver()]. En déclarant ce bean, on remplace celui de [Spring Boot] ;
lignes 45-56 : le résolveur est une classe imbriquée qui implémente l'interface [LocaleResolver] ;
lignes 48-50 : la méthode [resolveLocale] est appelée au début de chaque requête : elle rend l'anglais des États-Unis ([Locale.US]) si l'URL contient [lang=en], le français de France ([Locale.FRANCE]) sinon. [Spring MVC] range cette langue dans [LocaleContextHolder], où la retrouvent le bean [formats] et les objets utilitaires de [Thymeleaf] ;
lignes 53-55 : la méthode [setLocale] permettrait de changer la langue (en la mémorisant, par exemple, dans un cookie). Ici, la langue vient de l'URL : la méthode refuse de travailler en levant une exception.

C'est une façon simple de tester ; le chapitre suivant fera mieux.

4.4.3. Un dialecte Thymeleaf

La barre de navigation met en évidence le lien de la page courante (classe CSS [active] de [Bootstrap]). Le fichier [templates/fragments/navbar.html] montre trois façons d'écrire les liens :

<!--/* xmlns:ex : l'espace de noms de notre dialecte (utile aux éditeurs seulement) */-->
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3" th:fragment="navbar"
     xmlns:th="http://www.thymeleaf.org" xmlns:ex="http://exemple16">
  <span class="navbar-brand">Helpers</span>
  <div class="navbar-nav">
    <!--/* 1. une condition écrite dans la vue (chemin : cf. config/ModeleCommun.java) */-->
    <a class="nav-link" th:classappend="${chemin == '/'} ? 'active'" href="/">Accueil</a>
    <!--/* 2. notre dialecte : l'attribut ex:actif="..." */-->
    <a class="nav-link" href="/produits" ex:actif="/produits">Produits</a>
    <!--/* 3. une expression de lien @{...} : Spring fabrique l'URL, avec ses paramètres */-->
    <a class="nav-link" th:href="@{/produits(lang=en)}">Products (en)</a>
  </div>
</nav>

Commentons ce code :

ligne 3 : l'espace de noms [xmlns:ex], comme [xmlns:th], ne sert qu'aux éditeurs ;
ligne 7 : première façon de mettre en évidence le lien de la page courante : une condition écrite dans la vue, avec l'attribut [chemin] fourni par la classe [ModeleCommun] (identique à celle de l'exemple 15). Sans partie « sinon », l'opérateur conditionnel ne produit rien quand la condition est fausse, et [th:classappend] n'ajoute alors aucune classe. C'est la façon qu'utilise l'étude de cas ;
ligne 9 : deuxième façon, plus concise : un attribut « maison », [ex:actif], apporté par notre dialecte ;
ligne 11 : une expression de lien [@{...}]. [Spring] fabrique l'URL : les parenthèses contiennent des paramètres, ajoutés à l'URL ([?lang=en]). Nous verrons à l'exemple 21 qu'elles servent aussi à remplir les variables d'un chemin. Une expression de lien ajoute en outre, si besoin, le chemin de base de l'application quand celle-ci n'est pas installée à la racine du serveur.

Un dialecte est un ensemble d'attributs (ou de balises) qui partagent un préfixe : les attributs [th:] sont ceux du dialecte standard de [Thymeleaf]. Chaque attribut est traité par un processeur. Le fichier [aides/ActifDialect.java] :

package exemple16.aides;

import java.util.Set;

import org.thymeleaf.dialect.AbstractProcessorDialect;
import org.thymeleaf.processor.IProcessor;
import org.thymeleaf.standard.StandardDialect;

// un DIALECTE Thymeleaf : un ensemble d'attributs "maison", tous préfixés par
// [ex:] (ex:actif="..."). Déclaré comme bean (cf. WebConfig), il est ajouté
// automatiquement au moteur Thymeleaf par Spring Boot.
public class ActifDialect extends AbstractProcessorDialect {

    public ActifDialect() {
        // nom du dialecte, préfixe de ses attributs, priorité (celle des attributs th:)
        super("Actif", "ex", StandardDialect.PROCESSOR_PRECEDENCE);
    }

    // les "processeurs" du dialecte : un seul, pour l'attribut ex:actif
    @Override
    public Set<IProcessor> getProcessors(String prefixe) {
        return Set.of(new ActifProcessor(prefixe));
    }
}

ligne 12 : un dialecte qui ne fournit que des processeurs dérive de la classe [AbstractProcessorDialect] ;
ligne 16 : le nom du dialecte, le préfixe de ses attributs ([ex]) et sa priorité : la même que celle des attributs [th:] ;
lignes 21-23 : les processeurs du dialecte : un seul, celui de l'attribut [ex:actif]. [Set.of(...)] fabrique un ensemble non modifiable.

Le fichier [aides/ActifProcessor.java] :

package exemple16.aides;

import org.thymeleaf.context.ITemplateContext;
import org.thymeleaf.context.IWebContext;
import org.thymeleaf.engine.AttributeName;
import org.thymeleaf.model.IProcessableElementTag;
import org.thymeleaf.processor.element.AbstractAttributeTagProcessor;
import org.thymeleaf.processor.element.IElementTagStructureHandler;
import org.thymeleaf.templatemode.TemplateMode;

// le processeur de l'attribut ex:actif : <a href="/produits" ex:actif="/produits">
// reçoit la classe "active" si la page courante est sous ce chemin
public class ActifProcessor extends AbstractAttributeTagProcessor {

    public ActifProcessor(String prefixe) {
        // HTML ; balises <a> seulement ; attribut [ex:actif] ; priorité ; true : l'attribut
        // ex:actif est retiré de la page produite
        super(TemplateMode.HTML, prefixe, "a", false, "actif", true, 1000, true);
    }

    // appelée pour chaque balise <a> qui porte l'attribut ex:actif
    @Override
    protected void doProcess(ITemplateContext contexte, IProcessableElementTag balise,
            AttributeName nomAttribut, String valeur, IElementTagStructureHandler structure) {
        // le chemin de la page, lu dans la requête en cours
        String chemin = contexte instanceof IWebContext web ? web.getExchange().getRequest().getRequestPath() : "";
        boolean estActif = valeur.equals("/") ? chemin.equals("/") : chemin.startsWith(valeur);
        if (estActif) {
            // on ajoute la classe "active" à l'attribut class de la balise
            String classes = balise.getAttributeValue("class");
            structure.setAttribute("class", classes == null ? "active" : classes + " active");
        }
    }
}

Commentons ce code :

ligne 13 : un processeur d'attribut dérive de la classe [AbstractAttributeTagProcessor] ;
ligne 18 : son constructeur décrit ce qu'il traite : le mode HTML, le préfixe du dialecte, les balises [<a>] seulement, l'attribut [actif] (préfixé : [ex:actif]), une priorité, et [true] : l'attribut [ex:actif] sera retiré de la page produite ;
lignes 23-24 : la méthode [doProcess] est appelée pour chaque balise [<a>] qui porte l'attribut [ex:actif]. Elle reçoit le contexte de la vue, la balise, et la valeur de l'attribut ; l'objet [structure] permet de modifier la balise ;
ligne 26 : le processeur est du code [Java], et non une expression de vue : il a le droit de lire la requête en cours. Quand la vue est produite pour une requête web, le contexte est un [IWebContext], qui donne accès à l'échange (la requête et sa réponse) ; [getRequestPath()] rend le chemin demandé. L'écriture [contexte instanceof IWebContext web] teste le type du contexte et, s'il convient, le range dans la variable [web] ;
lignes 27-32 : si le chemin de la page commence par la valeur de l'attribut, on ajoute la classe [active] à l'attribut [class] de la balise.

Le code HTML de la barre de navigation, à l'URL [/produits] :

    <nav class="navbar navbar-expand bg-light rounded mb-3 px-3" xmlns:ex="http://exemple16">
  <span class="navbar-brand">Helpers</span>
  <div class="navbar-nav">

    <a class="nav-link" href="/">Accueil</a>

    <a class="nav-link active" href="/produits">Produits</a>

    <a class="nav-link" href="/produits?lang=en">Products (en)</a>
  </div>
</nav>

Le lien « Produits » a reçu la classe [active], et l'attribut [ex:actif] a disparu. L'expression de lien a produit [/produits?lang=en]. On remarque que [Thymeleaf] a retiré l'attribut [xmlns:th], mais pas l'attribut [xmlns:ex] : il ne connaît pas ce dernier. On aurait pu le laisser de côté, puisqu'il ne sert qu'aux éditeurs.

Le gabarit [layout.html] est celui de l'exemple 15, sans le pied de page (et le titre des pages se termine par [- Helpers] au lieu de [- Mon site]). Les pages obtenues, en français (http://localhost:5000/, http://localhost:5000/produits) puis en anglais (http://localhost:5000/produits?lang=en) :

Les prix changent de format avec la langue : [1 149,90 €] en français, [€1,149.90] en anglais. En français, les dollars sont notés [$US], pour les distinguer des autres dollars (canadiens, australiens...). Le code HTML du tableau, en français :

    <tbody>
      <tr>
        <td>CLAVIER</td>
        <td>25,00 €</td>
        <td>25,00 $US</td>

        <td><span class="badge text-bg-success">12 en stock</span></td>
      </tr>
      <tr>
        <td>SOURIS</td>
        <td>12,50 €</td>
        <td>12,50 $US</td>

        <td><span class="badge text-bg-danger">épuisé</span></td>
      </tr>
      <tr>
        <td>ÉCRAN</td>
        <td>1 149,90 €</td>
        <td>1 149,90 $US</td>

        <td><span class="badge text-bg-success">3 en stock</span></td>
      </tr>
    </tbody>

et en anglais ([/produits?lang=en]), où le dollar s'écrit simplement [$] :

    <tbody>
      <tr>
        <td>CLAVIER</td>
        <td>€25.00</td>
        <td>$25.00</td>

        <td><span class="badge text-bg-success">12 en stock</span></td>
      </tr>
      <tr>
        <td>SOURIS</td>
        <td>€12.50</td>
        <td>$12.50</td>

        <td><span class="badge text-bg-danger">épuisé</span></td>
      </tr>
      <tr>
        <td>ÉCRAN</td>
        <td>€1,149.90</td>
        <td>$1,149.90</td>

        <td><span class="badge text-bg-success">3 en stock</span></td>
      </tr>
    </tbody>

Seuls les montants ont changé : le texte des badges est écrit en dur dans le fragment (le chapitre suivant traduira les textes).

4.5. Exemple 17 : un formulaire GET

Un formulaire HTML envoyé par la méthode GET place ses champs dans l'URL. C'est la méthode qui convient à une recherche : elle ne modifie rien, et l'URL obtenue peut être mise en favori ou partagée. L'étude de cas l'utilise pour choisir un médecin et un jour.

Les fichiers [models/Livre.java] et [models/RechercheModele.java] :

package exemple17.models;

public record Livre(String titre, String auteur, String genre) {
}

package exemple17.models;

import java.util.List;

// le modèle de la vue : la saisie (pour la réafficher), les genres, les résultats
public record RechercheModele(String motCle, String genre, List<String> genres, List<Livre> resultats) {
}

ligne 6 : le modèle de la vue contient les valeurs saisies ([motCle], [genre]), pour que le formulaire les réaffiche, la liste des genres, et les résultats.

Le fichier [controllers/LivresController.java] :

package exemple17.controllers;

import java.util.List;
import java.util.Locale;

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

import exemple17.models.Livre;
import exemple17.models.RechercheModele;

@Controller
public class LivresController {

    private static final List<Livre> LIVRES = List.of(
            new Livre("Le Rouge et le Noir", "Stendhal", "roman"),
            new Livre("Les Fleurs du mal", "Baudelaire", "poésie"),
            new Livre("Madame Bovary", "Flaubert", "roman"),
            new Livre("Alcools", "Apollinaire", "poésie"),
            new Livre("Le Cid", "Corneille", "théâtre"));

    private static final List<String> GENRES = List.of("roman", "poésie", "théâtre");

    // GET / et GET /recherche?motCle=...&genre=... : le formulaire ET ses résultats
    @GetMapping({ "/", "/recherche" })
    public String recherche(@RequestParam(required = false) String motCle,
            @RequestParam(required = false) String genre, Model model) {
        String mot = motCle == null ? "" : motCle.trim().toLowerCase(Locale.ROOT);
        List<Livre> resultats = LIVRES.stream()
                .filter(l -> mot.isEmpty() || l.titre().toLowerCase(Locale.ROOT).contains(mot)
                        || l.auteur().toLowerCase(Locale.ROOT).contains(mot))
                .filter(l -> genre == null || genre.isEmpty() || l.genre().equals(genre))
                .toList();
        model.addAttribute("modele", new RechercheModele(motCle == null ? "" : motCle,
                genre == null ? "" : genre, GENRES, resultats));
        return "livres/recherche";
    }
}

Commentons ce code :

lignes 17-24 : les livres et les genres, en mémoire ;
ligne 27 : une même action peut répondre à plusieurs chemins : elle traite [GET /] et [GET /recherche] ;
lignes 28-29 : les paramètres [motCle] et [genre] sont liés aux paramètres de même nom de l'URL (cf. exemple 07). [required = false] les rend facultatifs : à la première visite, le formulaire n'a pas encore été envoyé, et ils valent [null] ;
lignes 31-35 : le filtrage, avec un flux ([stream]) [Java] (cf. exemple 06) : [stream()] parcourt la liste, chaque [filter] ne garde que les livres qui satisfont une condition, et [toList()] rassemble les livres retenus dans une nouvelle liste. Les conditions sont des lambdas : [l -> ...] est une fonction anonyme qui reçoit un livre [l] et rend un booléen. Un mot-clé vide ou un genre vide ne filtrent rien ;
lignes 36-37 : le modèle de la vue. On y remplace les [null] par des chaînes vides.

Le gabarit [templates/layout.html] est simplifié : un seul paramètre, le contenu de la page, et un titre fixe :

<!doctype html>
<html lang="fr" xmlns:th="http://www.thymeleaf.org" th:fragment="page(contenu)">
<head>
  <meta charset="utf-8">
  <title>Livres</title>
  <link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-3">
    <main th:replace="${contenu}"></main>
  </div>
</body>
</html>

ligne 2 : le fragment [page] n'a plus qu'un paramètre, [contenu] ;
ligne 5 : le titre est le même pour toutes les pages.

Le fichier [templates/livres/recherche.html] :

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main>
  <h1 class="h3">Recherche de livres</h1>
  <!--/* method="get" : les champs sont envoyés dans l'URL (?motCle=...&genre=...) */-->
  <form method="get" action="/recherche" class="row g-2 align-items-end mb-3">
    <div class="col-auto">
      <label class="form-label" for="motCle">Titre ou auteur</label>
      <!--/* th:value : le champ réaffiche ce qui a été saisi */-->
      <input class="form-control" id="motCle" name="motCle" th:value="${modele.motCle}">
    </div>
    <div class="col-auto">
      <label class="form-label" for="genre">Genre</label>
      <select class="form-select" id="genre" name="genre">
        <option value="">(tous)</option>
        <!--/* th:selected : un attribut booléen, écrit si la condition est vraie, omis sinon */-->
        <option th:each="genre : ${modele.genres}" th:value="${genre}" th:text="${genre}"
                th:selected="${genre == modele.genre}">roman</option>
      </select>
    </div>
    <div class="col-auto">
      <button class="btn btn-primary" type="submit">Rechercher</button>
    </div>
  </form>
  <p th:text="|${#lists.size(modele.resultats)} livre(s) trouvé(s).|">0 livre(s) trouvé(s).</p>
  <ul>
    <li th:each="livre : ${modele.resultats}"><i th:text="${livre.titre}">Titre</i>, [[${livre.auteur}]] ([[${livre.genre}]])</li>
  </ul>
</main>
</body>
</html>

Commentons ce code :

ligne 2 : la page passe au gabarit son seul paramètre, sa balise [<main>] ;
ligne 7 : [method="get"] et [action="/recherche"] : l'envoi du formulaire est une requête [GET /recherche?motCle=...&genre=...]. Le nom des paramètres est l'attribut [name] de chaque champ ;
ligne 11 : l'attribut [th:value] écrit l'attribut [value] du champ : il réaffiche la saisie. D'une façon générale, [th:xxx] calcule la valeur de l'attribut HTML [xxx] : [th:value], [th:href], [th:action], [th:class]...
lignes 18-19 : une option par genre. Sur la même balise, [th:each] est traité en premier, puis [th:value] et [th:text], qui utilisent la variable de la boucle. [th:selected] est un attribut booléen : si l'expression est vraie, [Thymeleaf] écrit [selected="selected"] ; si elle est fausse, il n'écrit pas l'attribut du tout. C'est exactement ce que demande le HTML, pour qui la seule présence de l'attribut [selected] suffit à sélectionner l'option. Il en va de même pour [th:checked], [th:disabled], [th:required], [th:readonly]... ;
ligne 26 : le nombre de résultats ;
ligne 28 : la liste des résultats, avec une balise [<i>] et deux expressions en ligne.

Le code HTML de la liste déroulante, après une recherche du genre [poésie] :

      <select class="form-select" id="genre" name="genre">
        <option value="">(tous)</option>

        <option value="roman">roman</option>

        <option value="poésie" selected="selected">poésie</option>

        <option value="théâtre">théâtre</option>
      </select>

Au premier affichage (http://localhost:5000/), puis après une recherche :

La barre d'adresse montre les paramètres envoyés. Les caractères accentués y sont codés ([%C3%A9] pour [é]) : c'est l'encodage URL, que [Spring MVC] décode avant la liaison des paramètres.

4.6. Exemple 18 : les champs d'un formulaire

L'exemple 18 réunit tous les types de champs HTML : texte, mot de passe, date, boutons radio, cases à cocher, liste déroulante, liste à sélection multiple, zone de texte, champ caché. Il montre comment le serveur les reçoit et comment la vue les réaffiche. Il présente aussi l'attribut [th:field], qui relie un champ du formulaire à une propriété d'un objet du modèle.

Le fichier [services/ListesService.java] :

package exemple18.services;

import java.util.List;

import org.springframework.stereotype.Service;

// les listes proposées par le formulaire. Dans une vraie application, elles
// viendraient d'une base de données : on les lirait UNE fois, au démarrage,
// puisqu'elles sont les mêmes pour tous les utilisateurs.
// @Service : un bean (singleton), trouvé par Spring comme les contrôleurs
@Service
public class ListesService {

    public record Pays(String code, String nom) {
    }

    public List<String> getTitres() {
        return List.of("Mr", "Mme", "Melle");
    }

    public List<Pays> getPays() {
        return List.of(new Pays("fr", "France"), new Pays("be", "Belgique"), new Pays("ch", "Suisse"),
                new Pays("ca", "Canada"));
    }

    public List<String> getLoisirs() {
        return List.of("lecture", "musique", "sport", "cinéma");
    }

    public List<String> getLangues() {
        return List.of("français", "anglais", "espagnol", "allemand");
    }
}

ligne 11 : l'annotation [@Service] fait de la classe un bean, comme [@Component] (exemple 16) : [Spring] la trouve au démarrage et en crée une instance unique, un singleton (cf. exemple 06), injectable dans les contrôleurs. [@Service] ne diffère de [@Component] que par l'intention qu'elle exprime : la classe est un service. Les listes proposées par le formulaire sont les mêmes pour tous les utilisateurs : un singleton est l'endroit naturel pour les garder ;
lignes 14-15 : un pays : un code et un nom ;
lignes 17-32 : les listes, rendues par des méthodes [getXxx()]. Pour une vue, ce sont les propriétés [titres], [pays], [loisirs] et [langues] du bean : [${listes.titres}] appellera [getTitres()].

Le fichier [models/Saisie.java] :

package exemple18.models;

import java.time.LocalDate;
import java.util.ArrayList;
import java.util.List;

import org.springframework.format.annotation.DateTimeFormat;

// ce que l'utilisateur a saisi : la liaison de modèle remplit chaque champ
// avec le paramètre de même nom (les listes reçoivent toutes les valeurs cochées)
public class Saisie {

    private String nom;
    private String motDePasse;
    private String commentaire;
    private String titre;
    private List<String> loisirs = new ArrayList<>();
    private String pays;
    private List<String> langues = new ArrayList<>();
    // un champ <input type="date"> envoie la date au format ISO : aaaa-mm-jj
    @DateTimeFormat(iso = DateTimeFormat.ISO.DATE)
    private LocalDate naissance;
    private String jeton;

    public String getNom() { return nom; }
    public void setNom(String nom) { this.nom = nom; }

    public String getMotDePasse() { return motDePasse; }
    public void setMotDePasse(String motDePasse) { this.motDePasse = motDePasse; }

    public String getCommentaire() { return commentaire; }
    public void setCommentaire(String commentaire) { this.commentaire = commentaire; }

    public String getTitre() { return titre; }
    public void setTitre(String titre) { this.titre = titre; }

    public List<String> getLoisirs() { return loisirs; }
    public void setLoisirs(List<String> loisirs) { this.loisirs = loisirs; }

    public String getPays() { return pays; }
    public void setPays(String pays) { this.pays = pays; }

    public List<String> getLangues() { return langues; }
    public void setLangues(List<String> langues) { this.langues = langues; }

    public LocalDate getNaissance() { return naissance; }
    public void setNaissance(LocalDate naissance) { this.naissance = naissance; }

    public String getJeton() { return jeton; }
    public void setJeton(String jeton) { this.jeton = jeton; }
}

Commentons ce code :

lignes 13-23 : la saisie est une classe [JavaBean] (des champs privés, un constructeur sans paramètre, des accesseurs [getXxx] et [setXxx]), et non un record : la liaison de modèle la crée vide, puis remplit chaque propriété avec le paramètre de même nom, par son accesseur [setXxx] ;
lignes 17 et 19 : les cases à cocher et la liste multiple sont des listes : elles reçoivent toutes les valeurs envoyées (cf. exemple 10). Elles sont initialisées à une liste vide, jamais [null] ;
lignes 21-22 : un champ [<input type="date">] envoie la date au format [ISO 8601] [aaaa-mm-jj]. L'annotation [@DateTimeFormat(iso = DateTimeFormat.ISO.DATE)] indique ce format à [Spring], qui s'en sert dans les deux sens : pour convertir le texte reçu en [LocalDate], et pour réécrire la date dans le champ.

Le fichier [controllers/FormulaireController.java] :

package exemple18.controllers;

import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;

import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ModelAttribute;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;

import exemple18.models.Saisie;
import exemple18.services.ListesService;
import jakarta.servlet.http.HttpServletRequest;

@Controller
@RequestMapping("/formulaire")
public class FormulaireController {

    private final ListesService listes;

    public FormulaireController(ListesService listes) {
        this.listes = listes;
    }

    // @ModelAttribute sur une méthode : exécutée avant CHAQUE action de ce
    // contrôleur, elle ajoute au modèle l'attribut [listes]
    @ModelAttribute("listes")
    public ListesService listes() {
        return listes;
    }

    // GET : le formulaire, avec des valeurs initiales
    @GetMapping("")
    public String afficher(Model model) {
        Saisie initial = new Saisie();
        initial.setTitre("Mme");
        initial.setPays("fr");
        initial.setLangues(List.of("français"));
        initial.setJeton("A7X2");
        model.addAttribute("saisie", initial);
        return "formulaire/formulaire";
    }

    // POST : la liaison de modèle remplit [saisie], ajoutée au modèle sous le nom
    // "saisie" (le nom de sa classe, première lettre en minuscule) ; on réaffiche
    @PostMapping("")
    public String traiter(@ModelAttribute Saisie saisie, HttpServletRequest request, Model model) {
        // ce que le navigateur a réellement envoyé, paramètre par paramètre
        Map<String, String[]> parametres = request.getParameterMap();
        String recu = parametres.entrySet().stream()
                .map(p -> p.getKey() + " = [" + String.join(", ", p.getValue()) + "]")
                .collect(Collectors.joining("\n"));
        model.addAttribute("recu", recu);
        return "formulaire/formulaire";
    }
}

Commentons ce code :

lignes 22-26 : le service des listes est injecté par le constructeur (cf. exemple 06) ;
lignes 30-33 : une méthode annotée par [@ModelAttribute("listes")], déclarée dans un contrôleur, est exécutée avant chaque action de ce contrôleur : les deux actions trouveront l'attribut [listes] dans leur modèle, sans avoir à l'y mettre (cf. [ModeleCommun], exemple 15, pour toutes les actions de l'application) ;
lignes 36-45 : [GET /formulaire] affiche le formulaire avec des valeurs initiales. L'objet est rangé dans le modèle sous le nom [saisie] ;
ligne 50 : [POST /formulaire] reçoit la saisie. L'annotation [@ModelAttribute], sur un paramètre, demande à la liaison de modèle de fabriquer l'objet à partir des paramètres de la requête (c'est le comportement par défaut pour un paramètre de type classe, cf. exemple 08), et de le ranger dans le modèle de la vue. Sans nom explicite, le nom de l'attribut est celui de la classe, avec une minuscule initiale : [saisie]. Le formulaire est réaffiché avec les valeurs reçues ;
lignes 52-56 : [getParameterMap()] donne en plus accès aux paramètres tels qu'ils ont été envoyés : un dictionnaire dont chaque valeur est un tableau de chaînes (un paramètre peut être répété). On en fait un texte, une ligne par paramètre, rangé dans le modèle sous le nom [recu]. [Collectors.joining("\n")] assemble les lignes, séparées par un saut de ligne.

Le gabarit [templates/layout.html] est celui de l'exemple 17 (seul le titre change). Le fichier [templates/formulaire/formulaire.html] :

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main>
  <h1 class="h3">Un formulaire complet</h1>
  <!--/* th:object : l'objet du formulaire ; *{...} désigne un champ de cet objet */-->
  <form method="post" action="/formulaire" th:object="${saisie}" style="max-width: 40rem">
    <!--/* champ caché : envoyé avec le formulaire, mais invisible */-->
    <input type="hidden" th:field="*{jeton}">

    <div class="mb-2">
      <span class="form-label me-3">Titre</span>
      <!--/* boutons radio : même [name], une seule valeur envoyée */-->
      <div class="form-check form-check-inline" th:each="titre : ${listes.titres}">
        <input class="form-check-input" type="radio" th:field="*{titre}" th:value="${titre}">
        <!--/* #ids.prev : l'id donné par th:field au champ qui précède */-->
        <label class="form-check-label" th:for="${#ids.prev('titre')}" th:text="${titre}">Mr</label>
      </div>
    </div>

    <div class="row g-2 mb-2">
      <div class="col">
        <label class="form-label" for="nom">Nom</label>
        <!--/* th:field fabrique les attributs id, name et value */-->
        <input class="form-control" type="text" th:field="*{nom}">
      </div>
      <div class="col">
        <label class="form-label" for="motDePasse">Mot de passe</label>
        <!--/* un mot de passe n'est JAMAIS renvoyé dans la page : pas de th:field */-->
        <input class="form-control" type="password" id="motDePasse" name="motDePasse">
      </div>
      <div class="col">
        <label class="form-label" for="naissance">Date de naissance</label>
        <!--/* un champ date échange ses valeurs au format aaaa-mm-jj */-->
        <input class="form-control" type="date" th:field="*{naissance}">
      </div>
    </div>

    <div class="mb-2">
      <span class="form-label me-3">Loisirs</span>
      <!--/* cases à cocher : même [name], plusieurs valeurs possibles */-->
      <div class="form-check form-check-inline" th:each="loisir : ${listes.loisirs}">
        <input class="form-check-input" type="checkbox" th:field="*{loisirs}" th:value="${loisir}">
        <label class="form-check-label" th:for="${#ids.prev('loisirs')}" th:text="${loisir}">lecture</label>
      </div>
    </div>

    <div class="row g-2 mb-2">
      <div class="col">
        <label class="form-label" for="pays">Pays</label>
        <select class="form-select" th:field="*{pays}">
          <option th:each="p : ${listes.pays}" th:value="${p.code}" th:text="${p.nom}">France</option>
        </select>
      </div>
      <div class="col">
        <label class="form-label" for="langues">Langues parlées</label>
        <!--/* liste à sélection multiple : plusieurs valeurs possibles */-->
        <select class="form-select" th:field="*{langues}" multiple size="4">
          <option th:each="langue : ${listes.langues}" th:value="${langue}" th:text="${langue}">français</option>
        </select>
      </div>
    </div>

    <div class="mb-2">
      <label class="form-label" for="commentaire">Commentaire</label>
      <!--/* une zone de texte : la valeur est ENTRE les balises */-->
      <textarea class="form-control" th:field="*{commentaire}" rows="2"></textarea>
    </div>

    <button class="btn btn-primary" type="submit">Envoyer</button>
  </form>

  <th:block th:if="${recu != null}">
    <h2 class="h5 mt-3">Ce que le serveur a reçu</h2>
    <pre class="bg-light p-2 border" th:text="${recu}">nom = [...]</pre>
  </th:block>
</main>
</body>
</html>

Commentons ce code :

ligne 7 : l'attribut [th:object] désigne l'objet du formulaire : l'attribut [saisie] du modèle. À l'intérieur de la balise, une expression de sélection [*{nom}] désigne la propriété [nom] de cet objet : c'est l'équivalent de [${saisie.nom}] ;
ligne 9 : l'attribut [th:field="*{jeton}"] relie le champ à la propriété [jeton] : il écrit les attributs [id] et [name] (le nom de la propriété) et l'attribut [value] (sa valeur). Un champ caché est envoyé avec le formulaire mais n'est pas affiché. Il sert à transporter une information d'une page à la suivante (l'étude de cas y met, par exemple, la version d'une fiche). Attention : l'utilisateur peut le modifier ;
lignes 14-18 : des boutons radio portent le même [name] : un seul peut être coché, et une seule valeur est envoyée. Pour un bouton radio, [th:field] n'écrit pas la valeur de la propriété dans [value] (c'est [th:value] qui donne la valeur du bouton) : il coche le bouton si sa valeur est égale à la propriété. Comme les boutons ont tous le même nom, [th:field] leur donne des [id] numérotés : [titre1], [titre2]... L'objet utilitaire [#ids.prev('titre')] (ligne 17) rend l'[id] donné au dernier champ [titre], pour l'attribut [for] de son libellé ;
ligne 25 : un champ texte : [th:field] écrit [id="nom"], [name="nom"] et la valeur. Le libellé de la ligne 23 peut donc écrire [for="nom"] en dur ;
ligne 30 : un mot de passe n'est jamais renvoyé dans une page : le champ n'utilise pas [th:field] et n'a pas d'attribut [value] ;
ligne 35 : un champ date. Le navigateur affiche la date dans son propre format, mais envoie et reçoit toujours [aaaa-mm-jj] ; [th:field] écrit la date dans ce format, grâce à l'annotation [@DateTimeFormat] ;
lignes 42-45 : des cases à cocher de même [name] : chaque case cochée envoie sa valeur, et le paramètre est donc répété. [th:field] coche la case si sa valeur appartient à la liste [loisirs] ;
lignes 51-53 : une liste déroulante. [th:field] sur la balise [<select>] sélectionne l'option dont la valeur est égale à la propriété [pays] ;
lignes 58-60 : l'attribut [multiple] permet de choisir plusieurs options : [th:field] sélectionne toutes celles qui appartiennent à la liste [langues] ;
ligne 67 : la valeur d'une zone de texte est entre ses balises, pas dans un attribut [value] : [th:field] le sait ;
lignes 73-76 : ce que le serveur a reçu, affiché seulement après un envoi, dans une balise [<pre>], qui respecte les sauts de ligne.

Voici un extrait du code HTML produit par ces attributs [th:field] (le champ caché, le deuxième bouton radio, les deux premières cases à cocher, la liste multiple) :

    <input type="hidden" id="jeton" name="jeton" value="A7X2">
...
      <div class="form-check form-check-inline">
        <input class="form-check-input" type="radio" value="Mme" id="titre2" name="titre" checked="checked">

        <label class="form-check-label" for="titre2">Mme</label>
      </div>
...
      <div class="form-check form-check-inline">
        <input class="form-check-input" type="checkbox" value="lecture" id="loisirs1" name="loisirs"><input type="hidden" name="_loisirs" value="on"/>
        <label class="form-check-label" for="loisirs1">lecture</label>
      </div>

      <div class="form-check form-check-inline">
        <input class="form-check-input" type="checkbox" value="musique" id="loisirs2" name="loisirs"><input type="hidden" name="_loisirs" value="on"/>
        <label class="form-check-label" for="loisirs2">musique</label>
      </div>
...
        <input type="hidden" name="_langues" value="1"/><select class="form-select" multiple size="4" id="langues" name="langues">
          <option value="français" selected="selected">français</option>

On y remarque des champs cachés que nous n'avons pas écrits : [_loisirs] après chaque case à cocher, [_langues] avant la liste multiple. Ils résolvent un problème du HTML : une case non cochée n'est pas envoyée du tout. Si l'utilisateur décoche toutes les cases, le paramètre [loisirs] est absent de la requête, et la liaison de modèle ne toucherait pas à la propriété [loisirs], qui garderait son ancienne valeur. Le marqueur [_loisirs], lui, est toujours envoyé : quand [Spring] le trouve sans le paramètre [loisirs], il vide la liste (ou met à [false] un booléen). Ici, la saisie est un objet neuf, dont la liste est déjà vide, et la différence ne se voit pas ; elle compte quand l'objet du formulaire a été rempli auparavant (par exemple, conservé en session, cf. chapitre « Portées des données »).

Le formulaire initial (http://localhost:5000/formulaire), puis après envoi :

On remarque que :

la zone de texte a réaffiché [Bonjour <b>tout</b> le monde] tel quel : [th:field] échappe la valeur, et les balises saisies ne sont pas interprétées ;
le mot de passe a été reçu mais n'est pas réaffiché ;
le navigateur a envoyé les marqueurs [_loisirs] (un par case) et [_langues].

Avec [curl], on voit la différence entre une case cochée :

1	`curl -d "jeton=A7X2&titre=Mr&nom=Martin&loisirs=sport" http://localhost:5000/formulaire`

    <pre class="bg-light p-2 border">jeton = [A7X2]
titre = [Mr]
nom = [Martin]
loisirs = [sport]</pre>

et deux cases cochées :

1	`curl -d "jeton=A7X2&titre=Mr&nom=Martin&loisirs=sport&loisirs=musique" http://localhost:5000/formulaire`

    <pre class="bg-light p-2 border">jeton = [A7X2]
titre = [Mr]
nom = [Martin]
loisirs = [sport, musique]</pre>

(seule la balise [<pre>] de la page est reproduite). L'option [-d] de [curl] envoie une requête POST, avec ce corps, et l'entête [Content-Type: application/x-www-form-urlencoded] d'un formulaire HTML.

4.7. Exemple 19 : la validation d'un formulaire

Un formulaire invalide doit être réaffiché, avec les valeurs saisies et un message sous chaque champ erroné. L'exemple 19 met en œuvre la technique de l'exemple 09 (validation faite par l'action, avec un paramètre [BindingResult]) sur un formulaire d'inscription, et montre comment [Thymeleaf] affiche les erreurs.

La validation demande une dépendance supplémentaire. Le fichier [pom.xml] :

  <dependencies>
    <!-- les vues Thymeleaf -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-thymeleaf</artifactId>
    </dependency>
    <!-- la validation (Bean Validation, Hibernate Validator) -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
  </dependencies>

lignes 7-11 : le starter de la validation : l'API [Bean Validation] (les annotations [@NotBlank], [@Size]...) et son implémentation, [Hibernate Validator] (cf. exemple 08).

Le fichier [models/InscriptionModele.java] :

package exemple19.models;

import java.util.Objects;

import jakarta.validation.constraints.AssertTrue;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Size;

// les champs du formulaire et leurs contraintes
public class InscriptionModele {

    @NotBlank(message = "Le nom est obligatoire.")
    @Size(max = 20, message = "Le nom ne doit pas dépasser 20 caractères.")
    private String nom;

    @NotBlank(message = "L'adresse électronique est obligatoire.")
    @Email(message = "Adresse électronique invalide.")
    private String email;

    // tout ce qui vient d'un formulaire est une chaîne : "42" -> 42
    @NotNull(message = "L'âge est obligatoire.")
    @Min(value = 18, message = "L'âge doit être compris entre 18 et 120 ans.")
    @Max(value = 120, message = "L'âge doit être compris entre 18 et 120 ans.")
    private Integer age;

    @NotBlank(message = "Le mot de passe est obligatoire.")
    @Size(min = 6, message = "Le mot de passe doit comporter au moins 6 caractères.")
    private String motDePasse;

    private String confirmation;

    // une règle qui porte sur DEUX champs : une méthode booléenne, validée par
    // @AssertTrue. Pour Bean Validation, c'est la propriété [confirmationValide].
    @AssertTrue(message = "La confirmation ne correspond pas au mot de passe.")
    public boolean isConfirmationValide() {
        return Objects.equals(motDePasse, confirmation);
    }

    public String getNom() { return nom; }
    public void setNom(String nom) { this.nom = nom; }

    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }

    public Integer getAge() { return age; }
    public void setAge(Integer age) { this.age = age; }

    public String getMotDePasse() { return motDePasse; }
    public void setMotDePasse(String motDePasse) { this.motDePasse = motDePasse; }

    public String getConfirmation() { return confirmation; }
    public void setConfirmation(String confirmation) { this.confirmation = confirmation; }
}

Commentons ce code :

lignes 16-18 : le nom est obligatoire ([@NotBlank] refuse [null], une chaîne vide et une chaîne faite d'espaces) et limité à 20 caractères ;
lignes 20-22 : [@Email] vérifie la forme d'une adresse électronique ;
lignes 25-28 : l'âge est converti en entier, puis validé. Le type [Integer] (et non [int]) permet la valeur [null] : un âge absent reste [null], et [@NotNull] le signale ;
lignes 30-32 : au moins 6 caractères. [@Size] ne vérifie pas une valeur [null] : c'est le rôle de [@NotBlank] ;
lignes 38-41 : la règle « la confirmation est égale au mot de passe » porte sur deux champs. [Bean Validation] n'a pas d'annotation toute faite pour cela ; le plus simple est une méthode booléenne qui fait la comparaison, annotée par [@AssertTrue] : la contrainte est violée si la méthode rend [false]. Pour [Bean Validation], une méthode [isXxx()] est l'accesseur d'une propriété booléenne : l'erreur éventuelle sera donc attachée à la propriété [confirmationValide]. [Objects.equals] compare deux objets, même [null].

Le fichier [controllers/InscriptionController.java] :

package exemple19.controllers;

import org.springframework.beans.propertyeditors.StringTrimmerEditor;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.validation.BindingResult;
import org.springframework.web.bind.WebDataBinder;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.InitBinder;
import org.springframework.web.bind.annotation.ModelAttribute;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;

import exemple19.models.InscriptionModele;
import jakarta.validation.Valid;

@Controller
@RequestMapping("/inscription")
public class InscriptionController {

    // @InitBinder : configure la liaison de modèle des actions de ce contrôleur.
    // StringTrimmerEditor(true) : chaque chaîne reçue est débarrassée de ses espaces
    // superflus, et une chaîne vide devient null
    @InitBinder
    public void initBinder(WebDataBinder binder) {
        binder.registerCustomEditor(String.class, new StringTrimmerEditor(true));
    }

    // ?html5=true : on laisse le navigateur valider le formulaire avant l'envoi
    @GetMapping("")
    public String afficher(@RequestParam(defaultValue = "false") boolean html5, Model model) {
        model.addAttribute("inscription", new InscriptionModele());
        model.addAttribute("html5", html5);
        return "inscription/inscription";
    }

    // @ModelAttribute("inscription") : le nom de l'objet dans le modèle de la vue
    @PostMapping("")
    public String inscrire(@Valid @ModelAttribute("inscription") InscriptionModele saisie, BindingResult resultat,
            @RequestParam(defaultValue = "false") boolean html5, Model model) {
        if (resultat.hasErrors()) {
            // on RÉAFFICHE le formulaire : valeurs saisies (sauf les mots de passe),
            // et un message sous chaque champ erroné (cf. fragments/champ.html)
            saisie.setMotDePasse(null);
            saisie.setConfirmation(null);
            model.addAttribute("html5", html5);
            model.addAttribute("erreur", "Le formulaire contient des erreurs.");
            return "inscription/inscription";
        }
        return "inscription/bienvenue";
    }
}

Commentons ce code :

lignes 25-28 : une méthode annotée par [@InitBinder] configure la liaison de modèle des actions de ce contrôleur. Elle reçoit l'objet [WebDataBinder] qui fait la liaison. On y enregistre un éditeur de propriétés pour le type [String] : [StringTrimmerEditor] retire les espaces au début et à la fin de chaque chaîne reçue ; avec l'argument [true], une chaîne vide devient [null]. Un nom saisi [" Martin "] devient ["Martin"]. Attention : cela vaut pour toutes les chaînes, mots de passe compris ;
lignes 31-36 : le formulaire vide. Le paramètre [html5] sera expliqué plus loin. L'objet du formulaire est rangé dans le modèle sous le nom [inscription] ;
ligne 40 : [@Valid] demande la validation de l'objet ; [@ModelAttribute("inscription")] le range dans le modèle sous le nom [inscription], le même qu'à la ligne 33, celui qu'utilise la vue. Le paramètre [BindingResult] doit suivre immédiatement l'objet validé : il reçoit les erreurs de liaison et de validation, et l'action est alors toujours exécutée (cf. exemple 09) ;
ligne 41 : [@RequestParam] lit un paramètre de l'URL ou du corps de la requête : ici, [html5] vient de l'URL du formulaire ;
lignes 42-50 : s'il y a des erreurs, on réaffiche le formulaire, avec les valeurs saisies, sauf les mots de passe, et un message global, rangé dans le modèle pour le gabarit. Il n'y a rien d'autre à faire : l'objet [inscription] et ses erreurs (le [BindingResult]) sont déjà dans le modèle, où la vue les trouvera ;
ligne 51 : sinon, la page de bienvenue, qui utilise elle aussi l'objet [inscription] du modèle.

Une erreur de conversion (un âge [abc]) produit par défaut un message en anglais, peu lisible : [Failed to convert property value of type java.lang.String to required type java.lang.Integer for property age; For input string: "abc"]. Le fichier [messages.properties] le remplace :

# les messages des erreurs de CONVERSION (ex. âge "abc"), en anglais par défaut ;
# la clé : typeMismatch.<type Java attendu>
typeMismatch.java.lang.Integer=La valeur saisie n''est pas un nombre entier.

ligne 3 : [Spring Boot] lit automatiquement le fichier [messages.properties] des ressources : c'est le fichier des messages de l'application (le chapitre suivant le déclinera en plusieurs langues). Pour une erreur de conversion, [Spring] cherche un message sous plusieurs clés, de la plus précise à la plus générale : [typeMismatch.inscription.age] (l'objet et sa propriété), [typeMismatch.age] (la propriété), [typeMismatch.java.lang.Integer] (le type attendu), enfin [typeMismatch]. La première trouvée l'emporte ; à défaut, c'est le message anglais. Dans ce fichier, l'apostrophe se double ([n''est]) : les messages sont traités par la classe [MessageFormat] de [Java], pour qui l'apostrophe simple est un caractère spécial. L'étude de cas remplace ainsi tous ces messages.

4.7.1. Un fragment de champ

Les champs sont tous construits sur le même modèle : un libellé, un champ, un message d'erreur. Un fragment les factorise. Le fichier [templates/fragments/champ.html] :

<!--/* un champ de saisie, avec son libellé et son message d'erreur. Le fragment n'a
       pas de signature : ses paramètres sont des variables nommées, facultatives :
       nom, libelle, type, et les contraintes HTML5 requis, maxlength, minlength,
       min, max. [erreurDe] : la propriété dont on affiche l'erreur (nom par défaut) */-->
<div class="mb-2" th:fragment="champ" th:with="cle=${erreurDe ?: nom}">
  <label class="form-label" th:for="${nom}" th:text="${libelle}">Libellé</label>
  <!--/* __${nom}__ : le PRÉTRAITEMENT ; ${nom} est évalué d'abord, et son résultat
         ("email") remplace l'expression : th:field="*{email}" */-->
  <input class="form-control" th:type="${type}" th:field="*{__${nom}__}"
         th:classappend="${#fields.hasErrors(cle)} ? 'is-invalid'"
         th:required="${requis}"
         th:attr="maxlength=${maxlength},minlength=${minlength},min=${min},max=${max}">
  <!--/* le PREMIER message d'erreur du champ, sous le champ */-->
  <div class="invalid-feedback" th:if="${#fields.hasErrors(cle)}" th:text="${#fields.errors(cle)[0]}">erreur</div>
</div>

Commentons ce code :

ligne 5 : le fragment [champ] est déclaré sans signature : sans liste de paramètres. On l'appellera avec des paramètres nommés ([champ(nom='age', libelle='Âge', ...)]), qui deviennent des variables du fragment ; un paramètre non fourni vaut simplement [null]. C'est pratique pour un fragment qui a beaucoup de paramètres facultatifs. [th:with] déclare la variable [cle] : le nom de la propriété dont on affiche l'erreur. L'opérateur [?:] (dit « Elvis ») rend son opérande de gauche s'il n'est pas [null], celui de droite sinon : [erreurDe] s'il est fourni, [nom] sinon ;
ligne 9 : [th:type] écrit l'attribut [type]. [th:field] doit recevoir le nom de la propriété, qui est dans la variable [nom]. On ne peut pas écrire [*{nom}] (ce serait la propriété [nom]) : on utilise le prétraitement [__...__]. L'expression entre doubles soulignés est évaluée d'abord, et son résultat remplace le texte : si [nom] vaut [email], l'attribut devient [th:field="*{email}"], qui est ensuite évalué normalement. [th:field] utilise l'objet du formulaire ([th:object]), déclaré par la vue qui insère le fragment ;
ligne 10 : [#fields.hasErrors(cle)] dit si la propriété a des erreurs dans le [BindingResult] de l'objet du formulaire. La classe [Bootstrap] [is-invalid] encadre alors le champ en rouge ;
ligne 11 : l'attribut booléen [required] est écrit si [requis] est vrai, omis sinon ;
ligne 12 : [th:attr] écrit plusieurs attributs à la fois. Un attribut dont la valeur est [null] n'est pas écrit : chaque champ ne reçoit que les contraintes HTML5 qui le concernent ;
ligne 14 : le message d'erreur, sous le champ (classe [Bootstrap] [invalid-feedback]). [#fields.errors(cle)] rend la liste des messages de la propriété ; une propriété peut violer plusieurs contraintes, et l'on n'affiche que le premier ([[0]]).

Le fichier [templates/inscription/inscription.html] :

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main>
  <h1 class="h3">Inscription</h1>
  <p th:if="${html5}">Validation par le navigateur <b>activée</b> - <a href="/inscription">la désactiver</a></p>
  <p th:unless="${html5}">Validation par le navigateur <b>désactivée</b> - <a href="/inscription?html5=true">l'activer</a></p>
  <!--/* novalidate : le navigateur ignore les attributs required, min... et
         envoie le formulaire tel quel ; seul le serveur valide */-->
  <form method="post" th:action="${html5} ? '/inscription?html5=true' : '/inscription'"
        th:novalidate="${!html5}" th:object="${inscription}">
    <div th:replace="~{fragments/champ :: champ(nom='nom', libelle='Nom', type='text', requis=true, maxlength=20)}"></div>
    <div th:replace="~{fragments/champ :: champ(nom='email', libelle='Adresse électronique', type='email', requis=true)}"></div>
    <div th:replace="~{fragments/champ :: champ(nom='age', libelle='Âge', type='number', requis=true, min=18, max=120)}"></div>
    <div th:replace="~{fragments/champ :: champ(nom='motDePasse', libelle='Mot de passe', type='password', requis=true, minlength=6)}"></div>
    <div th:replace="~{fragments/champ :: champ(nom='confirmation', libelle='Confirmation', type='password', requis=true, erreurDe='confirmationValide')}"></div>
    <button class="btn btn-primary" type="submit">S'inscrire</button>
  </form>
</main>
</body>
</html>

lignes 6-7 : le lien qui active ou désactive la validation par le navigateur ;
ligne 10 : l'attribut [action] du formulaire garde le paramètre [html5] ;
ligne 11 : l'attribut booléen [novalidate] est écrit quand [html5] est faux. [th:object] désigne l'objet du formulaire, [inscription] ;
lignes 12-16 : chaque champ est une insertion du fragment, avec des paramètres nommés. Pour la confirmation (ligne 16), l'erreur à afficher est celle de la propriété [confirmationValide], celle de la règle [@AssertTrue].

Le fichier [templates/layout.html] :

<!doctype html>
<html lang="fr" xmlns:th="http://www.thymeleaf.org" th:fragment="page(contenu)">
<head>
  <meta charset="utf-8">
  <title>Inscription</title>
  <link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-3" style="max-width: 36rem">
    <main th:replace="${contenu}"></main>
    <!--/* l'erreur globale, en bas de page, sur fond rose léger ; [erreur] est déposée par l'action */-->
    <div class="zone-erreur" role="alert" th:if="${erreur != null}" th:text="${erreur}">erreur</div>
  </div>
</body>
</html>

ligne 13 : le message global est affiché en bas de la page, sur un fond rose léger (classe [zone-erreur] de [static/css/styles.css]), comme dans l'étude de cas.

Le fichier [templates/inscription/bienvenue.html] :

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main th:object="${inscription}">
  <h1 class="h3" th:text="|Bienvenue *{nom}|">Bienvenue</h1>
  <p>Votre inscription est enregistrée : adresse <b th:text="*{email}">email</b>, âge <b th:text="*{age}">42</b> ans.</p>
</main>
</body>
</html>

ligne 4 : [th:object] n'est pas réservé aux formulaires : sur la balise [<main>], il permet d'écrire [*{nom}] au lieu de [${inscription.nom}] ;
lignes 5-6 : les valeurs converties et nettoyées : l'âge est un nombre, le nom a perdu ses espaces.

Le formulaire vide (http://localhost:5000/inscription), puis envoyé avec plusieurs erreurs (un nom fait d'espaces, une adresse incomplète, un âge trop petit, des mots de passe trop courts et différents) :

puis correctement rempli (avec des espaces autour du nom) :

Et avec un âge non numérique, envoyé par [curl] (le navigateur l'aurait refusé dans un champ [type="number"]) :

1	`curl -i -d "nom=Martin&email=xx&age=abc" http://localhost:5000/inscription`

HTTP/1.1 200
Content-Type: text/html;charset=UTF-8

<!doctype html>
<html lang="fr">
<head>
  <meta charset="utf-8">
  <title>Inscription</title>
  <link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-3" style="max-width: 36rem">
    <main>
  <h1 class="h3">Inscription</h1>

  <p>Validation par le navigateur <b>désactivée</b> - <a href="/inscription?html5=true">l'activer</a></p>

  <form method="post" action="/inscription" novalidate="novalidate">
    <div class="mb-2">
  <label class="form-label" for="nom">Nom</label>

  <input class="form-control" type="text" maxlength="20" required="required" id="nom" name="nom" value="Martin">


</div>
    <div class="mb-2">
  <label class="form-label" for="email">Adresse électronique</label>

  <input class="form-control is-invalid" type="email" required="required" id="email" name="email" value="xx">

  <div class="invalid-feedback">Adresse électronique invalide.</div>
</div>
    <div class="mb-2">
  <label class="form-label" for="age">Âge</label>

  <input class="form-control is-invalid" type="number" min="18" max="120" required="required" id="age" name="age" value="">

  <div class="invalid-feedback">La valeur saisie n&#39;est pas un nombre entier.</div>
</div>
    <div class="mb-2">
  <label class="form-label" for="motDePasse">Mot de passe</label>

  <input class="form-control is-invalid" type="password" minlength="6" required="required" id="motDePasse" name="motDePasse" value="">

  <div class="invalid-feedback">Le mot de passe est obligatoire.</div>
</div>
    <div class="mb-2">
  <label class="form-label" for="confirmation">Confirmation</label>

  <input class="form-control" type="password" required="required" id="confirmation" name="confirmation" value="">


</div>
    <button class="btn btn-primary" type="submit">S'inscrire</button>
  </form>
</main>

    <div class="zone-erreur" role="alert">Le formulaire contient des erreurs.</div>
  </div>
</body>
</html>

On remarque que :

l'erreur de conversion de l'âge utilise le message de [messages.properties] ;
le champ [age] ne réaffiche pas la valeur rejetée [abc] : pour un champ [type="number"], [th:field] n'écrit pas une valeur qui n'est pas un nombre (avec [type="text"], il aurait écrit [value="abc"]) ;
le mot de passe absent n'a qu'une erreur, « obligatoire » : [@Size] ne vérifie pas une valeur [null]. La confirmation, elle, n'en a pas : deux mots de passe absents sont égaux ;
les champs non erronés n'ont pas la classe [is-invalid], et leur fragment ne produit pas de message.

4.7.2. La validation par le navigateur

Les attributs [required], [maxlength], [min], [max], [type="email"]... demandent au navigateur de vérifier le formulaire avant de l'envoyer : l'utilisateur est prévenu immédiatement, par une bulle d'aide, sans aller-retour avec le serveur. C'est le comportement obtenu avec le lien « l'activer » (http://localhost:5000/inscription?html5=true), qui retire l'attribut [novalidate] du formulaire.

Cette validation est un confort, pas une protection : il suffit de retirer l'attribut [required] avec les outils de développement du navigateur, ou d'envoyer la requête avec [curl], pour la contourner. La validation par le serveur reste indispensable. C'est pourquoi l'exemple désactive par défaut la validation du navigateur : pour voir travailler le serveur. L'étude de cas, elle, garde les deux : les attributs HTML5 pour le confort, et la validation serveur pour la sûreté.

4.8. Exemple 20 : le schéma Post / Redirect / Get

Quand un formulaire POST réussit, l'action peut afficher directement une page. Le problème apparaît si l'utilisateur recharge ensuite cette page (touche F5) : le navigateur renvoie le formulaire, et l'opération est faite une seconde fois (une commande passée deux fois, un rendez-vous pris deux fois...). Le schéma Post / Redirect / Get (PRG) évite ce problème : une action POST réussie ne fabrique pas de page, elle redirige vers une page GET. Recharger cette page ne refait qu'un GET, sans effet.

Reste un détail : la page GET doit afficher un message (« la tâche a été ajoutée »), alors que ce message a été produit par l'action POST, dans une autre requête. [Spring MVC] fournit pour cela les attributs flash : des attributs déposés avant la redirection, qui survivent jusqu'à la requête suivante, où ils sont ajoutés au modèle, puis disparaissent. C'est ce qu'on appelle un message flash. Par défaut, [Spring MVC] conserve les attributs flash dans la session HTTP de l'utilisateur : une mémoire que le serveur associe à chaque navigateur (le chapitre « Portées des données » lui est consacré).

Le fichier [services/TachesService.java] :

package exemple20.services;

import java.util.List;
import java.util.concurrent.CopyOnWriteArrayList;

import org.springframework.stereotype.Service;

// la liste des tâches, en mémoire, partagée par tous (singleton).
// CopyOnWriteArrayList : une liste utilisable par plusieurs requêtes simultanées
@Service
public class TachesService {

    private final List<String> taches = new CopyOnWriteArrayList<>(List.of("Lire le chapitre 3"));

    public List<String> liste() {
        return List.copyOf(taches);
    }

    public void ajouter(String libelle) {
        taches.add(libelle);
    }
}

ligne 13 : un singleton est partagé par toutes les requêtes, qui peuvent s'exécuter en même temps. Une [ArrayList] ordinaire ne le supporte pas ; [CopyOnWriteArrayList] est une liste prévue pour cet usage ;
lignes 15-17 : [List.copyOf] rend une copie non modifiable de la liste : l'appelant ne peut pas modifier la liste du service.

Le fichier [controllers/TachesController.java] :

package exemple20.controllers;

import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.servlet.mvc.support.RedirectAttributes;

import exemple20.services.TachesService;

@Controller
@RequestMapping("/taches")
public class TachesController {

    private final TachesService taches;

    public TachesController(TachesService taches) {
        this.taches = taches;
    }

    // GET /taches : la liste et le formulaire d'ajout
    @GetMapping("")
    public String afficher(Model model) {
        model.addAttribute("taches", taches.liste());
        return "taches/taches";
    }

    // POST /taches : le schéma Post / Redirect / Get
    @PostMapping("")
    public String ajouter(@RequestParam(required = false) String libelle, Model model,
            RedirectAttributes redirection) {
        String texte = libelle == null ? "" : libelle.trim();
        if (texte.isEmpty() || texte.length() > 40) {
            // saisie invalide : on réaffiche la page, sans redirection
            model.addAttribute("libelle", libelle);
            model.addAttribute("erreur", "Le libellé doit comporter de 1 à 40 caractères.");
            return afficher(model);
        }
        taches.ajouter(texte);
        // un attribut "flash" : il survivra à la redirection, pour la requête SUIVANTE
        redirection.addFlashAttribute("flash", "La tâche [" + texte + "] a été ajoutée.");
        // pas de page : une redirection vers la page GET
        return "redirect:/taches";
    }

    // POST /taches/sans-prg : le contre-exemple (une page en réponse au POST)
    @PostMapping("/sans-prg")
    public String ajouterSansPrg(@RequestParam(required = false) String libelle, Model model) {
        taches.ajouter(libelle == null || libelle.isBlank() ? "(sans titre)" : libelle.trim());
        model.addAttribute("sansPrg", true);
        return afficher(model);
    }
}

Commentons ce code :

lignes 24-28 : la page de la liste ;
ligne 33 : un paramètre de type [RedirectAttributes], fourni par [Spring MVC] : les attributs de la redirection ;
lignes 35-40 : une saisie invalide : on réaffiche la page, sans redirection (il faut garder la saisie et le message d'erreur). La ligne 39 appelle simplement la méthode [afficher], comme n'importe quelle méthode [Java] : elle ajoute la liste des tâches au modèle et rend le nom de la vue ;
ligne 43 : une saisie valide : après l'opération, [addFlashAttribute] dépose le message flash ;
ligne 45 : une chaîne qui commence par [redirect:] n'est pas un nom de vue : [Spring MVC] répond par une redirection (code 302) vers l'adresse qui suit (cf. exemple 04) ;
lignes 49-54 : le contre-exemple, pour comparer : une page en réponse au POST.

Le fichier [templates/taches/taches.html] :

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main>
  <h1 class="h3">Mes tâches</h1>
  <ol>
    <li th:each="tache : ${taches}" th:text="${tache}">tâche</li>
  </ol>
  <form method="post" action="/taches" class="d-flex gap-2">
    <input class="form-control" name="libelle" th:value="${libelle}" placeholder="Nouvelle tâche">
    <button class="btn btn-primary text-nowrap" type="submit">Ajouter</button>
    <!--/* formaction : ce bouton envoie le MÊME formulaire à une autre adresse */-->
    <button class="btn btn-outline-secondary text-nowrap" type="submit" formaction="/taches/sans-prg">Ajouter sans PRG</button>
  </form>
  <p class="text-danger mt-2" th:if="${sansPrg}">Page affichée en réponse à un POST : appuyez sur F5 et la tâche sera ajoutée une seconde fois.</p>
</main>
</body>
</html>

ligne 10 : la saisie, réaffichée après une erreur (l'attribut [libelle] n'existe pas dans les autres cas : le champ est vide) ;
ligne 13 : l'attribut [formaction] d'un bouton envoie le formulaire à une autre adresse que celle de l'attribut [action] du formulaire. Le formulaire a ainsi deux boutons, qui déclenchent deux actions différentes. L'étude de cas utilise ce procédé sur sa page de connexion ;
ligne 15 : un attribut absent du modèle vaut [null], et [th:if] considère [null] comme faux.

Le fichier [templates/layout.html] :

<!doctype html>
<html lang="fr" xmlns:th="http://www.thymeleaf.org" th:fragment="page(contenu)">
<head>
  <meta charset="utf-8">
  <title>Tâches</title>
  <link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-3" style="max-width: 36rem">
    <!--/* le message flash, en haut de page : un attribut du modèle, déposé AVANT la redirection */-->
    <div class="alert alert-success" role="status" th:if="${flash != null}" th:text="${flash}">flash</div>
    <main th:replace="${contenu}"></main>
    <div class="zone-erreur" role="alert" th:if="${erreur != null}" th:text="${erreur}">erreur</div>
  </div>
</body>
</html>

Le message flash est affiché en haut de la page (ligne 12), l'erreur en bas (ligne 14). Pour la vue, un attribut flash est un attribut du modèle comme un autre.

Voici ce que voit [curl] pour l'envoi réussi du formulaire. L'option [-c fichier] enregistre les cookies reçus, [-b fichier] les renvoie ; [--data-urlencode] code les espaces et les accents du champ :

1	`curl -i -c cookies.txt -b cookies.txt --data-urlencode "libelle=Réviser Spring" http://localhost:5000/taches`

HTTP/1.1 302
Set-Cookie: JSESSIONID=06182248E838DA1EE6C9473288FD57A3; Path=/; HttpOnly
Location: http://localhost:5000/taches
Content-Length: 0

La réponse est une redirection vers [/taches]. Pour ranger le message flash, [Spring MVC] a créé une session HTTP : le serveur ([Tomcat]) lui a donné un identifiant, envoyé au navigateur dans le cookie [JSESSIONID]. La requête suivante renvoie ce cookie, ce qui permet au serveur de retrouver la session et le message :

1	`curl -i -c cookies.txt -b cookies.txt http://localhost:5000/taches`

HTTP/1.1 200
Content-Type: text/html;charset=UTF-8

<!doctype html>
<html lang="fr">
<head>
  <meta charset="utf-8">
  <title>Tâches</title>
  <link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-3" style="max-width: 36rem">

    <div class="alert alert-success" role="status">La tâche [Réviser Spring] a été ajoutée.</div>
    <main>
  <h1 class="h3">Mes tâches</h1>
  <ol>
    <li>Lire le chapitre 3</li>
    <li>Réviser Spring</li>
  </ol>
  <form method="post" action="/taches" class="d-flex gap-2">
    <input class="form-control" name="libelle" value="" placeholder="Nouvelle tâche">
    <button class="btn btn-primary text-nowrap" type="submit">Ajouter</button>

    <button class="btn btn-outline-secondary text-nowrap" type="submit" formaction="/taches/sans-prg">Ajouter sans PRG</button>
  </form>

</main>

  </div>
</body>
</html>

Le message flash est affiché ; si l'on recharge la page, il a disparu. La session, elle, reste ouverte : son identifiant ne change pas, et le serveur ne renvoie pas le cookie.

Le fichier [application.properties] contient un réglage lié à la session :

# le port d'écoute du serveur (8080 par défaut)
server.port=5000
# les réponses d'erreur de Spring Boot ne contiennent pas la pile d'appels
spring.web.error.include-stacktrace=never
# la session (qui transporte les attributs flash) est suivie par un cookie
# seulement, jamais par un ";jsessionid=..." ajouté aux URL
server.servlet.session.tracking-modes=cookie

ligne 7 : la session est suivie par un cookie seulement. Sans ce réglage, [Tomcat] ne sait pas, lors de la première réponse, si le navigateur accepte les cookies : il envoie le cookie, mais ajoute aussi l'identifiant de session aux URL de redirection. On obtient alors :

HTTP/1.1 302
Set-Cookie: JSESSIONID=C8AE990DF14A06FBBC2EEC72C3D4A832; Path=/; HttpOnly
Location: http://localhost:5000/taches;jsessionid=C8AE990DF14A06FBBC2EEC72C3D4A832
Content-Length: 0

L'URL [/taches;jsessionid=...] fonctionne, mais elle s'affiche dans la barre d'adresse du navigateur, et un identifiant de session qui circule dans les URL (historique, favoris, liens copiés) est un risque de sécurité. Tous les exemples qui utilisent des attributs flash ont ce réglage.

Dans le navigateur (http://localhost:5000/taches), après l'ajout d'une tâche :

La barre d'adresse affiche [/taches] : c'est la page GET. On peut la recharger sans risque, le message disparaît. Une saisie faite d'espaces :

Et le contre-exemple :

Ici, la barre d'adresse affiche [/taches/sans-prg], l'adresse du POST. Recharger la page provoque un avertissement du navigateur (« confirmer le renvoi du formulaire »), puis ajoute la tâche une seconde fois. Tous les formulaires POST de l'étude de cas suivent le schéma PRG. L'étude de cas range cependant ses attributs flash dans un cookie plutôt que dans la session, car son serveur ne garde rien entre deux requêtes.

4.9. Exemple 21 : liens, boutons et confirmation

Une règle simple guide le choix entre un lien et un bouton :

un lien ([<a href>]) produit une requête GET. Une requête GET ne doit rien modifier : les navigateurs, les moteurs de recherche, les antivirus se permettent de suivre des liens tout seuls, pour préparer une page ou l'analyser ;
une opération qui modifie des données (ajouter, modifier, supprimer, se déconnecter) est un bouton dans un formulaire POST.

L'exemple 21 gère une liste de contacts : on consulte un contact par un lien, on le supprime par un bouton, avec une fenêtre de confirmation. Les fichiers de l'exemple :

21-liens-boutons/
├── src/
│   └── main/
│       ├── java/
│       │   └── exemple21/
│       │       ├── config/
│       │       │   └── WebConfig.java
│       │       ├── controllers/
│       │       │   └── ContactsController.java
│       │       ├── services/
│       │       │   └── ContactsService.java
│       │       └── Exemple21Application.java
│       └── resources/
│           ├── static/
│           │   ├── css/
│           │   │   └── styles.css
│           │   └── js/
│           │       └── app.js
│           ├── templates/
│           │   ├── contacts/
│           │   │   ├── fiche.html
│           │   │   └── liste.html
│           │   ├── fragments/
│           │   │   └── confirmation.html
│           │   └── layout.html
│           └── application.properties
└── pom.xml

Le fichier [services/ContactsService.java] :

package exemple21.services;

import java.util.ArrayList;
import java.util.List;
import java.util.Optional;

import org.springframework.stereotype.Service;

// les contacts, en mémoire, partagés par tous (singleton)
@Service
public class ContactsService {

    // un contact : un identifiant, un nom, un numéro de téléphone
    public record Contact(int id, String nom, String telephone) {
    }

    private final List<Contact> contacts = new ArrayList<>(List.of(
            new Contact(1, "Marie Durand", "01 23 45 67 89"),
            new Contact(2, "Paul Martin", "06 12 34 56 78"),
            new Contact(3, "Philippe Jandot", "02 98 76 54 32")));
    private int dernierId = 3;

    // synchronized : une seule requête à la fois exécute la méthode
    public synchronized List<Contact> liste() {
        return List.copyOf(contacts);
    }

    // Optional : un contact, ou "rien" s'il n'existe pas
    public synchronized Optional<Contact> lire(int id) {
        return contacts.stream().filter(c -> c.id() == id).findFirst();
    }

    public synchronized Optional<Contact> modifier(int id, String nom, String telephone) {
        for (int i = 0; i < contacts.size(); i++) {
            if (contacts.get(i).id() == id) {
                // un record est immuable : on le remplace par un nouveau
                Contact modifie = new Contact(id, nom, telephone);
                contacts.set(i, modifie);
                return Optional.of(modifie);
            }
        }
        return Optional.empty();
    }

    public synchronized Contact ajouter(String nom, String telephone) {
        Contact contact = new Contact(++dernierId, nom, telephone);
        contacts.add(contact);
        return contact;
    }

    public synchronized Optional<Contact> supprimer(int id) {
        Optional<Contact> contact = lire(id);
        contact.ifPresent(contacts::remove);
        return contact;
    }
}

Commentons ce code :

lignes 14-15 : un contact ;
lignes 17-20 : la liste des contacts : une [ArrayList] (modifiable), initialisée avec trois contacts ;
ligne 24 : le mot-clé [synchronized] garantit qu'une seule requête à la fois exécute une méthode [synchronized] de l'objet : les requêtes simultanées ne peuvent pas modifier la liste en même temps. C'est une autre solution que la liste [CopyOnWriteArrayList] de l'exemple 20 ;
lignes 29-31 : [lire] rend un [Optional<Contact>] (cf. exemple 06) : un objet qui contient un contact, ou rien si aucun contact n'a cet identifiant. [findFirst()] rend le premier élément du flux, dans un [Optional] ;
lignes 36-38 : un record est immuable : on ne modifie pas ses champs, on le remplace par un nouveau ;
ligne 46 : [++dernierId] incrémente le compteur avant de l'utiliser : les identifiants suivants sont 4, 5... ;
ligne 53 : [ifPresent] exécute une action si l'[Optional] contient un contact. [contacts::remove] est une référence de méthode : une façon courte d'écrire la lambda [c -> contacts.remove(c)].

Le fichier [controllers/ContactsController.java] :

package exemple21.controllers;

import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.server.ResponseStatusException;
import org.springframework.web.servlet.mvc.support.RedirectAttributes;

import exemple21.services.ContactsService;
import exemple21.services.ContactsService.Contact;

@Controller
@RequestMapping("/contacts")
public class ContactsController {

    private final ContactsService contacts;

    public ContactsController(ContactsService contacts) {
        this.contacts = contacts;
    }

    // un LIEN (<a href>) : une requête GET, qui ne modifie rien
    @GetMapping("")
    public String liste(Model model) {
        model.addAttribute("contacts", contacts.liste());
        return "contacts/liste";
    }

    @GetMapping("/{id:\\d+}")
    public String fiche(@PathVariable int id, Model model) {
        model.addAttribute("contact", contacts.lire(id).orElseThrow(ContactsController::introuvable));
        return "contacts/fiche";
    }

    // un BOUTON dans un formulaire POST : une requête qui modifie des données
    @PostMapping("/{id:\\d+}")
    public String enregistrer(@PathVariable int id, @RequestParam String nom, @RequestParam String telephone,
            RedirectAttributes redirection) {
        Contact contact = contacts.modifier(id, nom, telephone).orElseThrow(ContactsController::introuvable);
        redirection.addFlashAttribute("flash", "Le contact [" + contact.nom() + "] a été modifié.");
        return "redirect:/contacts";
    }

    // même formulaire, autre bouton (attribut formaction) : autre action
    @PostMapping("/{id:\\d+}/dupliquer")
    public String dupliquer(@PathVariable int id, @RequestParam String nom, @RequestParam String telephone,
            RedirectAttributes redirection) {
        Contact copie = contacts.ajouter(nom + " (copie)", telephone);
        redirection.addFlashAttribute("flash", "Le contact [" + copie.nom() + "] a été créé.");
        return "redirect:/contacts";
    }

    @PostMapping("/{id:\\d+}/supprimer")
    public String supprimer(@PathVariable int id, RedirectAttributes redirection) {
        Contact contact = contacts.supprimer(id).orElseThrow(ContactsController::introuvable);
        redirection.addFlashAttribute("flash", "Le contact [" + contact.nom() + "] a été supprimé.");
        return "redirect:/contacts";
    }

    // une exception qui produit une réponse 404
    private static ResponseStatusException introuvable() {
        return new ResponseStatusException(HttpStatus.NOT_FOUND, "contact inconnu");
    }
}

Commentons ce code :

lignes 28-38 : les deux pages : la liste et la fiche d'un contact. La contrainte [{id:\\d+}] (cf. exemple 02) n'accepte qu'un identifiant fait de chiffres ;
ligne 36 : [orElseThrow] rend le contact contenu dans l'[Optional] ou, s'il est vide, lève l'exception fabriquée par la fonction qu'on lui passe : ici la référence de méthode [ContactsController::introuvable] ;
lignes 41-47 : l'enregistrement d'une fiche, en PRG. Les paramètres [nom] et [telephone] sont obligatoires : [@RequestParam] sans [required = false] ;
lignes 50-56 : la duplication, déclenchée par un second bouton du même formulaire (attribut [formaction]) ;
lignes 58-63 : la suppression, par un POST ;
lignes 66-68 : une exception [ResponseStatusException] porte un code HTTP et une raison. Levée par une action, elle produit une réponse d'erreur avec ce code : ici 404. Un contact inexistant provoque ainsi une 404 dans les actions [fiche], [enregistrer] et [supprimer] ; la duplication, elle, ne relit pas le contact : elle crée une copie à partir des champs reçus.

Le fichier [templates/contacts/liste.html] :

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main>
  <h1 class="h3">Contacts</h1>
  <table class="table align-middle">
    <tbody>
      <tr th:each="contact : ${contacts}">
        <td th:text="${contact.nom}">Marie Durand</td>
        <td th:text="${contact.telephone}">01 23 45 67 89</td>
        <td class="text-end">
          <!--/* consulter : un simple lien ; @{/contacts/{id}(id=...)} : une URL avec variable */-->
          <a class="btn btn-sm btn-outline-primary" th:href="@{/contacts/{id}(id=${contact.id})}">Voir</a>
          <!--/* supprimer : un formulaire POST, dont l'envoi sera confirmé */-->
          <form method="post" class="d-inline" th:action="@{/contacts/{id}/supprimer(id=${contact.id})}"
                th:data-confirmation="|Supprimer le contact ${contact.nom} ?|">
            <button class="btn btn-sm btn-outline-danger" type="submit">Supprimer</button>
          </form>
        </td>
      </tr>
    </tbody>
  </table>
</main>
</body>
</html>

ligne 13 : consulter : un lien, présenté comme un bouton par [Bootstrap]. L'expression de lien [@{/contacts/{id}(id=${contact.id})}] contient une variable de chemin [{id}], remplie par le paramètre de même nom entre parenthèses : [/contacts/1]. Un paramètre qui ne correspond à aucune variable du chemin est ajouté après [?] (cf. exemple 16) ;
lignes 15-16 : supprimer : un petit formulaire POST, réduit à son bouton. L'attribut [data-confirmation] contient la question à poser avant l'envoi. Les attributs [data-*] sont libres : le HTML les ignore, le [JavaScript] de la page peut les lire. [Thymeleaf] sait écrire n'importe quel attribut : [th:data-confirmation] calcule l'attribut [data-confirmation], dont la valeur est échappée.

Le fichier [templates/contacts/fiche.html] :

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main th:object="${contact}">
  <h1 class="h3" th:text="|Contact n° *{id}|">Contact n° 1</h1>
  <form method="post" th:action="@{/contacts/{id}(id=*{id})}">
    <div class="mb-2">
      <label class="form-label" for="nom">Nom</label>
      <input class="form-control" id="nom" name="nom" th:value="*{nom}">
    </div>
    <div class="mb-3">
      <label class="form-label" for="telephone">Téléphone</label>
      <input class="form-control" id="telephone" name="telephone" th:value="*{telephone}">
    </div>
    <!--/* deux boutons d'envoi pour un même formulaire */-->
    <button class="btn btn-primary" type="submit">Enregistrer</button>
    <button class="btn btn-outline-primary" type="submit" th:formaction="@{/contacts/{id}/dupliquer(id=*{id})}">Dupliquer</button>
    <a class="btn btn-link" href="/contacts">Retour à la liste</a>
  </form>
</main>
</body>
</html>

ligne 4 : [th:object] sur la balise [<main>] : le contact est l'objet sélectionné, et [*{id}] désigne son identifiant ;
ligne 6 : l'adresse du formulaire, avec une variable de chemin remplie par une expression de sélection ;
lignes 9 et 13 : ce formulaire n'utilise pas [th:field] : les champs ne sont pas liés à un objet de formulaire, [th:value] suffit ;
lignes 16-17 : deux boutons d'envoi pour un même formulaire ; le second a son propre attribut [formaction].

4.9.1. La fenêtre de confirmation

La boîte de dialogue du navigateur ([window.confirm]) ne peut être ni mise en forme, ni traduite : ses boutons restent dans la langue du navigateur. On la remplace par une fenêtre [Bootstrap], écrite dans la page et cachée tant qu'on n'en a pas besoin. Le fichier [templates/fragments/confirmation.html] :

<!--/* une seule fenêtre pour toute la page, cachée (d-none) au départ */-->
<div id="modale-confirmation" class="d-none" th:fragment="confirmation">
  <div class="modal-backdrop fade show"></div>
  <div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true">
    <div class="modal-dialog modal-dialog-centered">
      <div class="modal-content">
        <div class="modal-header">
          <h5 class="modal-title">Confirmation</h5>
        </div>
        <div class="modal-body">
          <p class="mb-0" id="modale-confirmation-message"></p>
        </div>
        <div class="modal-footer">
          <button type="button" class="btn btn-secondary" data-action="non">Non, revenir</button>
          <button type="button" class="btn btn-danger" data-action="oui">Oui, confirmer</button>
        </div>
      </div>
    </div>
  </div>
</div>

ligne 2 : un fragment sans paramètre. La classe [d-none] cache la fenêtre ;
ligne 3 : le fond grisé ;
ligne 11 : l'emplacement de la question ;
lignes 14-15 : les deux boutons, repérés par un attribut [data-action].

Le fichier [templates/layout.html] :

<!doctype html>
<html lang="fr" xmlns:th="http://www.thymeleaf.org" th:fragment="page(contenu)">
<head>
  <meta charset="utf-8">
  <title>Contacts</title>
  <link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-3" style="max-width: 40rem">
    <div class="alert alert-success" role="status" th:if="${flash != null}" th:text="${flash}">flash</div>
    <main th:replace="${contenu}"></main>
  </div>
  <!--/* la fenêtre de confirmation, présente dans toutes les pages */-->
  <div th:replace="~{fragments/confirmation :: confirmation}"></div>
  <!--/* le script, en fin de page : les éléments qu'il cherche existent déjà */-->
  <script src="/js/app.js"></script>
</body>
</html>

ligne 11 : le message flash ;
ligne 15 : la fenêtre est présente dans toutes les pages ;
ligne 17 : le script est chargé en fin de page : quand il s'exécute, les éléments qu'il cherche existent déjà. Il est servi comme fichier statique, depuis [static/js/app.js].

Un peu de [JavaScript] fait le lien entre les formulaires et la fenêtre. Le fichier [static/js/app.js] :

// confirmation des formulaires portant l'attribut data-confirmation="..."
// Sans JavaScript, ces formulaires partent simplement sans confirmation.
(() => {
  const modale = document.getElementById('modale-confirmation');
  const message = document.getElementById('modale-confirmation-message');
  let enAttente = null; // le formulaire à envoyer si l'on confirme

  // 1. on intercepte l'envoi des formulaires à confirmer
  document.querySelectorAll('form[data-confirmation]').forEach((formulaire) => {
    formulaire.addEventListener('submit', (evenement) => {
      evenement.preventDefault(); // l'envoi est suspendu
      enAttente = formulaire;
      message.textContent = formulaire.dataset.confirmation;
      modale.classList.remove('d-none'); // la fenêtre apparaît
    });
  });

  // 2. les deux boutons de la fenêtre
  modale.addEventListener('click', (evenement) => {
    const action = evenement.target.dataset.action;
    if (action === 'oui') {
      enAttente.submit(); // envoi, SANS redéclencher l'événement 'submit'
    } else if (action === 'non') {
      modale.classList.add('d-none');
      enAttente = null;
    }
  });
})();

ligne 3 : le code est enveloppé dans une fonction exécutée aussitôt, pour ne pas créer de variables globales ;
lignes 9-16 : on intercepte l'envoi de chaque formulaire qui porte l'attribut [data-confirmation]. [preventDefault()] suspend l'envoi ; on mémorise le formulaire, on place la question dans la fenêtre ([textContent], et non [innerHTML] : la question est affichée comme du texte, jamais interprétée comme du HTML) et on affiche la fenêtre ;
lignes 19-27 : « Oui » envoie le formulaire mémorisé. La méthode [submit()] d'un formulaire l'envoie sans déclencher l'événement [submit] : il n'y a pas de nouvelle demande de confirmation. « Non » cache la fenêtre.

Si le [JavaScript] est désactivé, les formulaires partent simplement sans confirmation : l'application fonctionne toujours. C'est le principe d'amélioration progressive : le [JavaScript] ajoute un confort, il n'est pas indispensable. L'étude de cas suit ce principe (son script [static/js/app.js] ajoute la gestion du clavier : touche Échap, focus). Les pages obtenues, à partir de http://localhost:5000/contacts : la liste, la demande de confirmation, la liste après suppression, la fiche d'un contact :

Enfin, on vérifie que la suppression ne peut pas être déclenchée par une requête GET :

1	`curl -i http://localhost:5000/contacts/2/supprimer`

HTTP/1.1 405
Allow: POST
Content-Type: application/json

{"timestamp":"2026-09-25T16:54:31.432Z","status":405,"error":"Method Not Allowed","message":"Method 'GET' is not supported.","path":"/contacts/2/supprimer"}

Le chemin existe, mais pas pour la méthode GET : [Spring MVC] répond [405 Method Not Allowed], et l'entête [Allow] indique la méthode acceptée. Le corps de la réponse est la réponse d'erreur de [Spring Boot], en JSON pour [curl] (un navigateur, qui demande du HTML, reçoit une page d'erreur). Avec POST :

1	`curl -i -X POST http://localhost:5000/contacts/2/supprimer`

HTTP/1.1 302
Set-Cookie: JSESSIONID=75BB430912EFA204402F7F5688560CF1; Path=/; HttpOnly
Location: http://localhost:5000/contacts
Content-Length: 0

La suppression a eu lieu, suivie de la redirection vers la liste ; le cookie [JSESSIONID] est celui de la session qui transporte le message flash. Et un contact inexistant :

1	`curl -i http://localhost:5000/contacts/99`

HTTP/1.1 404
Content-Type: application/json

{"timestamp":"2026-09-25T16:54:31.498Z","status":404,"error":"Not Found","message":"contact inconnu","path":"/contacts/99"}

La réponse 404 reprend la raison donnée à l'exception [ResponseStatusException] ([contact inconnu]). Ce champ [message] n'est présent que pendant le développement : les outils de développement de [Spring Boot] ([devtools], une dépendance de tous les exemples) activent son affichage ; sans eux, la réponse ne contient que le code, l'erreur et le chemin.