Skip to content

4. A view e seu modelo

Até este ponto, as actions geraram suas próprias respostas: texto, JSON e algumas tags HTML escritas como uma string. Em uma aplicação MVC, esse é o papel de uma view: um arquivo que descreve a página HTML, com marcadores de posição para os dados que a action lhe repassa, o modelo da view. [Spring MVC] não fornece uma linguagem de views por si só: ele pode trabalhar com várias engines de views ([Thymeleaf], [FreeMarker], [Mustache], [JSP]...). Este curso usa o [Thymeleaf], a engine de views mais utilizada junto com o [Spring MVC], que o [Spring Boot] consegue configurar sozinho.

Uma view [Thymeleaf] é um arquivo [.html] padrão: um arquivo HTML válido que pode ser aberto como está em um navegador. Os dados são inseridos nele por meio de atributos adicionais com o prefixo [th:] ([th:text], [th:if], [th:each]...), que o [Thymeleaf] executa no servidor e depois remove da página. É o que o [Thymeleaf] chama de templates naturais ([natural templates]): um designer gráfico pode trabalhar na view sem iniciar a aplicação, e o desenvolvedor adiciona a ela os atributos [th:]. Isso difere do [Razor], a engine de views do [ASP.NET Core MVC], que combina HTML e código [C#] precedido pelo caractere [@].

4.1. Exemplo 13: Uma primeira view

Para usar o [Thymeleaf], basta adicionar uma dependência ao arquivo [pom.xml] do exemplo:

1
2
3
4
5
6
7
  <dependencies>
    <!-- as views Thymeleaf -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-thymeleaf</artifactId>
    </dependency>
  </dependencies>
  • Linhas 3–6: o [spring-boot-starter-thymeleaf] starter. Um starter é uma dependência “tudo em um”: ele fornece o [Thymeleaf], sua integração com o [Spring] (a biblioteca [thymeleaf-spring6]) e a configuração automática do [Spring Boot], que os vincula ao [Spring MVC]. Não há mais nada a escrever: nenhuma versão (ela é definida pelo projeto pai [spring-boot-starter-parent]), nenhuma classe de configuração.

O modelo da view é uma classe simples. O arquivo [models/PageModel.java]:

1
2
3
4
5
package example13.models;

// o modelo da view: os dados que a ação passa para a view
public record PageModel(String title, String message, String time) {
}
  • Linha 4: Um record [Java] (veja o Exemplo 03) é uma classe cujos campos são definidos de uma vez por todas pelo construtor: neste caso, três strings [title], [message], and [time]. O compilador gera automaticamente o construtor e os acessores que leem os campos para nós. Observação: esses acessores têm o nome do campo ([title()]), e não [getTitle()] como em uma classe chamada [JavaBean] (veja o Exemplo 08). É uma forma concisa de escrever uma classe que apenas transporta dados.

O arquivo [controllers/ViewsController.java]:

package example13.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 example13.models.PageModel;

// @Controller: as ações retornam o NOME de uma view
@Controller
public class ViewsController {

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

    // Model: o modelo da view, um dicionário preenchido pela ação;
    // a string retornada é o nome da view: templates/views/index.html
    @GetMapping("/")
    public String index(Model model) {
        PageModel pageModel = new PageModel(
                "My first view",
                "This page was built by Thymeleaf, on the server.",
                LocalTime.now().format(TIME));
        model.addAttribute("model", pageModel);
        return "views/index";
    }

    // ModelAndView: a view, seu modelo e, se necessário, o código de resposta, em um único objeto
    @GetMapping("/hello/{name}")
    public ModelAndView hello(@PathVariable String name) {
        if (name.equals("unknown")) {
            return new ModelAndView("views/unknown", Map.of("name", name), HttpStatus.NOT_FOUND);
        }
        PageModel pageModel = new PageModel(
                "Hello " + name,
                "This time, the action built a ModelAndView object.",
                LocalTime.now().format(TIME));
        return new ModelAndView("views/index", Map.of("model", pageModel));
    }
}

Vamos comentar este código:

  • Linha 17: A anotação [@Controller] substitui a anotação [@RestController] dos exemplos anteriores. Com [@RestController], o que uma action devolve é a resposta (texto, JSON). Com [@Controller], uma action que devolve uma string devolve o nome de uma view: é a view que gerará a resposta;
  • linha 25: a action recebe um parâmetro do tipo [Model], fornecido pelo [Spring MVC]. Este é o modelo da view: um dicionário, em que cada entrada (um atributo) associa um nome a um objeto;
  • Linhas 26–30: A action cria um objeto [PageModel] (um título, uma mensagem, a hora atual) e o armazena no modelo com o nome [model]. A view o recuperará com esse nome;
  • linha 31: a action devolve o nome da view, [views/index]. Ela não cria mais a resposta; em vez disso, faz referência a uma view e preparou seus dados;
  • linha 36: a action [hello] devolve um objeto [ModelAndView], que combina o nome da view e seu modelo em um único objeto. Esta é outra forma de escrever uma action que usa uma view;
  • Linha 38: Quando a view depende da requisição, a action seleciona a view. Aqui, o nome [unknown] exibe a view [views/unknown], com código de status 404: o terceiro argumento do construtor de [ModelAndView] é o código da resposta. O modelo dessa view contém uma string simples: o nome solicitado. [Map.of(...)] cria um dicionário somente leitura;
  • linha 44: as duas actions compartilham a mesma view, [views/index], com modelos diferentes.

Onde o [Spring MVC] procura a view [views/index]? Ele passa o nome da view a um view resolver ([ViewResolver]), que o converte em uma view específica. O configurado pelo [Spring Boot] para o [Thymeleaf] ([ThymeleafViewResolver]) adiciona um prefixo, [classpath:/templates/], e um sufixo, [.html]: A view [views/index] é o arquivo [templates/views/index.html] no classpath, ou seja, as pastas e os arquivos compactados em que a máquina virtual [Java] procura as classes e os recursos da aplicação. A pasta [src/main/resources] do projeto faz parte dele: seu conteúdo é copiado pelo [Maven] para [target/classes], junto com as classes compiladas. Esses dois valores podem ser alterados em [application.properties] (propriedades [spring.thymeleaf.prefix] e [spring.thymeleaf.suffix]). Diferentemente do [ASP.NET Core MVC], não há nenhuma convenção que derive o nome da view dos nomes do controller e da action: a action sempre especifica o caminho da view, relativo à pasta [templates]. Os arquivos do projeto:

13-first-view/
├── src/
│   └── main/
│       ├── java/
│       │   └── example13/
│       │       ├── controllers/
│       │       │   └── ViewsController.java
│       │       ├── models/
│       │       │   └── PageModel.java
│       │       └── Example13Application.java
│       └── resources/
│           ├── templates/
│           │   └── views/
│           │       ├── index.html
│           │       └── unknown.html
│           └── application.properties
└── pom.xml

O arquivo [templates/views/index.html]:

<!doctype html>
<!--/* xmlns:th: declara o namespace dos atributos th:... (útil para os editores) */-->
<html lang="en" xmlns:th="http://www.thymeleaf.org">
<head>
  <meta charset="utf-8">
  <title th:text="${model.title}">Page title</title>
</head>
<body>
  <h1 th:text="${model.title}">Page title</h1>
  <p th:text="${model.message}">A message.</p>
  <p>Page built at <span th:text="${model.time}">12:00:00</span>.</p>
</body>
</html>

Vamos comentar este código:

  • Linha 2: Um comentário [Thymeleaf] é escrito como [<!--/* ... */-->]. É um comentário HTML cujo conteúdo é delimitado por [/*] e [*/]: o [Thymeleaf] o remove da página renderizada, ao passo que um comentário HTML comum ([<!-- -->]) seria enviado ao navegador;
  • Linha 3: O atributo [xmlns:th] declara o namespace dos atributos [th:]. Ele se destina exclusivamente aos editores de código (autocompletar, validação): o [Thymeleaf] processa os atributos [th:] mesmo sem ele, e o remove da página gerada;
  • Linha 6: O atributo [th:text] substitui o conteúdo da tag pelo valor da expressão. [${model.title}] é uma expressão de variável: [model] é o atributo do modelo definido pela action, e [.title] chama seu acessor, [title()]. O texto “Page Title” escrito dentro da tag é apenas um exemplo, exibido quando o arquivo é aberto diretamente em um navegador; ele desaparece da página gerada;
  • linhas 9–11: o mesmo princípio se aplica ao título, à mensagem e à hora. Para inserir um valor no meio de um texto, envolva-o em uma tag [<span>], que contém o atributo [th:text].

[${...}] expressões são escritas na linguagem de expressões do [Spring], [SpEL] ([Spring Expression Language]). [model.title] chama o método [getTitle()] de um [JavaBean], ou o método [title()] de um record: o mesmo código é escrito nos dois casos.

Uma view [Thymeleaf] não é compilada com a aplicação: ela é lida e interpretada quando a página é solicitada. Um erro em uma view, portanto, não é relatado em tempo de compilação, mas sim quando a página é exibida. Se você escrever [${model.titl}] na view, a requisição falha (código de status 500) e o console do servidor exibe: [Property or field 'titl' cannot be found on object of type 'example13.models.PageModel']. Da mesma forma, um nome de view que não corresponde a nenhum arquivo causa o erro [Error resolving template [views/missing], template might not exist or might not be accessible by any of the configured Template Resolvers]. O resultado, em http://localhost:5000/:

Image

O código-fonte da página recebida pelo navegador não contém mais nenhum vestígio do [Thymeleaf]:

curl http://localhost:5000/
<!doctype html>

<html lang="en">
<head>
  <meta charset="utf-8">
  <title>My first view</title>
</head>
<body>
  <h1>My first view</h1>
  <p>This page was built by Thymeleaf, on the server.</p>
  <p>Page built at <span>18:53:46</span>.</p>
</body>
</html>

Observe que:

  • os atributos [th:text] desapareceram, substituídos pelos valores do modelo, assim como o atributo [xmlns:th];
  • o comentário [Thymeleaf] desapareceu, mas deixa uma linha em branco;
  • os caracteres acentuados, se houver (esta página em inglês não tem nenhum), são escritos como estão ([é], [è]...): [Thymeleaf] escapa apenas os caracteres que têm significado em HTML ([<], [>], [&], ["], [']). [Razor], por outro lado, codifica por padrão os caracteres acentuados ([&#xE8;] para [è]), o que obriga o curso de [ASP.NET Core MVC] a alterar uma configuração; aqui não há essa exigência.

A URL http://localhost:5000/hello/martin exibe a mesma view usando um modelo diferente:

Image

Se o texto contivesse um apóstrofo, o código HTML desta página o mostraria como [&#39;]: este é um dos caracteres escapados por [th:text]. A URL http://localhost:5000/hello/unknown mostra uma view diferente:

curl -i http://localhost:5000/hello/unknown
HTTP/1.1 404
Content-Type: text/html;charset=UTF-8

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

  <h1>Nobody is called [unknown] here.</h1>
</body>
</html>

A resposta tem de fato o código de status 404 definido pelo objeto [ModelAndView] (o [Tomcat] envia apenas o código, sem seu rótulo [Not Found]). O arquivo [templates/views/unknown.html]:

<!doctype html>
<html lang="en" xmlns:th="http://www.thymeleaf.org">
<head>
  <meta charset="utf-8">
  <title>Unknown</title>
</head>
<body>
  <!--/* |...|: um texto em que as expressões ${...} são substituídas */-->
  <h1 th:text="|Nobody is called [${name}] here.|">Nobody is called [xx] here.</h1>
</body>
</html>
  • linha 9: o texto delimitado por duas barras verticais, [|...|], é uma substituição literal: as expressões [${...}] que ele contém são substituídas por seus valores. Isso é mais legível do que uma sequência de [<span>]. [${name}] é o atributo [name] do modelo, uma string simples.

4.2. Exemplo 14: A linguagem do Thymeleaf

Uma view [Thymeleaf] não contém nenhum código [Java]: tudo é tratado por meio dos atributos [th:] e das expressões que eles contêm. Ainda assim, ela contém condições, laços, variáveis locais e chamadas de método. Esse poder exige disciplina: a view deve continuar sendo um elemento de formatação; os cálculos e as decisões pertencem à action e aos serviços. O Exemplo 14 apresenta uma visão geral da sintaxe. O modelo, arquivo [models/BasicsModel.java]:

package example14.models;

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

public record BasicsModel(
        String title,
        String name,
        String nickname,
        String html,
        boolean loggedIn,
        String currency,
        List<Product> products,
        List<Product> cart,
        Address address) {

    public record Product(String name, BigDecimal price, boolean inStock) {
    }

    public record Address(String street, String city) {
    }
}
  • linhas 6–15: o modelo é um record: algumas strings, um booleano, duas listas de produtos e um endereço;
  • Linhas 17–21: Dois records aninhados dentro do primeiro: [BasicsModel.Product] e [BasicsModel.Address]. Um preço é um [BigDecimal]; esse tipo [Java] representa números decimais exatos (um [double] não consegue representar exatamente [0.1]).

O arquivo [controllers/BasicsController.java]:

package example14.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 example14.models.BasicsModel;
import example14.models.BasicsModel.Address;
import example14.models.BasicsModel.Product;

@Controller
public class BasicsController {

    @GetMapping("/")
    public String index(Model model) {
        BasicsModel basicsModel = new BasicsModel(
                "Thymeleaf basics",
                "Martin",
                null,
                "<b>this is HTML</b>",
                true,
                "€",
                List.of(
                        new Product("Keyboard", new BigDecimal("25"), true),
                        new Product("Mouse", new BigDecimal("12.5"), false),
                        new Product("Screen", new BigDecimal("149"), true)),
                List.of(),
                new Address("12 rue des Lilas", "Angers"));
        model.addAttribute("model", basicsModel);
        return "basics/index";
    }
}
  • Linhas 19–31: A action preenche o modelo: algumas strings, um booleano, uma lista de três produtos, um carrinho de compras vazio e um endereço. O apelido (linha 22) é intencionalmente definido como [null]. [List.of(...)] cria uma lista somente leitura; [List.of()] cria uma lista vazia.

A view, arquivo [templates/basics/index.html]:

<!doctype html>
<html lang="en" xmlns:th="http://www.thymeleaf.org">
<head>
  <meta charset="utf-8">
  <title th:text="${model.title}">Title</title>
</head>
<!--/* th:with: variáveis locais, utilizáveis na tag e em seus descendentes */-->
<body th:with="total=${#aggregates.sum(model.products.![price])}, count=${#lists.size(model.products)}">
  <h1 th:text="${model.title}">Title</h1>
  <!--/* 1. exibir um valor do modelo; null não exibe nada. Este Thymeleaf
         do Thymeleaf não aparece na página produzida */-->
  <p>1. Name: <span th:text="${model.name}">name</span> - nickname: [<span th:text="${model.nickname}">nickname</span>]</p>
  <!--/* 2. th:text escapa o HTML, th:utext o insere como está */-->
  <p>2a. <span th:text="${model.html}">html</span></p>
  <p>2b. <span th:utext="${model.html}">html</span></p>
  <!--/* 3. uma condição: th:if exibe a tag se a condição for verdadeira, th:unless se for falsa */-->
  <p th:if="${model.loggedIn}">3. You are logged in.</p>
  <p th:unless="${model.loggedIn}">3. You are not logged in.</p>
  <!--/* 4. um laço: a tag que carrega th:each é repetida; stat: o estado do laço */-->
  <p>4. Our products:</p>
  <ul>
    <li th:each="product, stat : ${model.products}">no. [[${stat.index}]]: [[${product.name}]], [[${product.price}]] [[${model.currency}]]
      <span th:text="${product.inStock} ? '(in stock)' : '(sold out)'">(in stock)</span>
      <th:block th:if="${stat.first}">- the first one</th:block>
      <th:block th:if="${stat.last}">- the last one, seen by [[${model.name}]]</th:block>
    </li>
  </ul>
  <!--/* 5. a lista vazia */-->
  <p>5. Your cart:
    <th:block th:if="${#lists.isEmpty(model.cart)}">it is empty.</th:block>
    <span th:each="p : ${model.cart}" th:text="${p.name}">product</span>
  </p>
  <!--/* 6. expressões calculadas, as variáveis de th:with e um utilitário (#numbers) */-->
  <p th:text="|6. ${count} products, for a total of ${total} ${model.currency}; average price: ${#numbers.formatDecimal(total.doubleValue() / count, 1, 2)} ${model.currency}|">6.</p>
  <p>7. Address: [[${model.address.street}]], [[${#strings.toUpperCase(model.address.city)}]]</p>
  <p>8. Um endereço de e-mail: contact@example.com</p>
</body>
</html>

Vamos comentar este código:

  • Linha 8: O atributo [th:with] declara variáveis locais que podem ser usadas dentro da tag que o contém e em todas as suas tags filhas (neste caso, [total] e [count]) em todo o corpo da página. [model.products.![price]] é uma projeção do [SpEL]: a lista de preços dos produtos. [#aggregates] e [#lists] são objetos utilitários do [Thymeleaf] (eles começam com [#]): [#aggregates.sum] calcula a soma de uma lista de números; [#lists.size] conta os elementos de uma lista;
  • linhas 10–11: um comentário [Thymeleaf], que está ausente da página gerada;
  • linha 12: um valor [null] ([${model.nickname}]) não exibe nada, sem erro;
  • linhas 14–15: [th:text] escapa os caracteres especiais do HTML ([<] torna-se [&lt;]...): o texto é exibido como está. [th:utext] ([unescaped text]) o insere sem escape: ele é interpretado como HTML. [th:utext] é usado apenas para HTML gerado pela aplicação, nunca para dados digitados por um usuário: o usuário poderia injetar HTML, ou até mesmo [JavaScript], na página (um ataque conhecido como [XSS], [cross-site scripting]);
  • Linhas 17–18: uma condição. [th:if] mantém a tag (e seu conteúdo) se a expressão for verdadeira e a remove caso contrário; [th:unless] faz o oposto. Não existe [th:else]: escrevemos a condição oposta;
  • Linha 22: um laço. O atributo [th:each] repete a tag que o contém, neste caso, [<li>], uma vez para cada item da lista. [product] é o item atual; [stat], que é opcional, é o contador da iteração: [stat.index] (começando em 0), [stat.count] (começando em 1), [stat.size], [stat.first], [stat.last], [stat.even], [stat.odd]. No texto da tag, [[[${product.name}]]] é uma expressão inline: ela insere o valor, escapado como em [th:text], sem a tag [<span>] (a forma [[(...)]] insere sem escape, como [th:utext]);
  • linha 23: o operador condicional [condition ? value1 : value2]. As strings literais são escritas entre aspas simples;
  • linhas 24–25: [th:block] é uma tag específica do [Thymeleaf]: ela serve apenas para carregar os atributos [th:] e desaparece da página gerada, deixando somente seu conteúdo. [stat.first] e [stat.last] verificam a posição no laço;
  • linhas 30–31: o caso de uma lista vazia. [#lists.isEmpty] verifica se a lista está vazia; um laço [th:each] sobre uma lista vazia não produz nada;
  • linha 34: uma substituição literal [|...|] que usa as variáveis de [th:with], e duas chamadas de método: [total.doubleValue()] converte [BigDecimal] em [double], e [#numbers.formatDecimal(value, 1, 2)] formata um número com pelo menos um dígito antes da vírgula decimal e exatamente dois depois;
  • linha 35: uma referência a [model.address.street], e o objeto utilitário [#strings], que agrupa operações sobre strings ([toUpperCase], [isEmpty], [contains], [startsWith]...);
  • linha 36: o [Thymeleaf] processa apenas os atributos [th:] e as expressões inline [[[...]]]; o restante do texto é copiado como está. O caractere [@] não tem significado específico aqui.

O resultado, em http://localhost:5000/:

Image

O código HTML produzido:

curl http://localhost:5000/
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Thymeleaf basics</title>
</head>

<body>
  <h1>Thymeleaf basics</h1>

  <p>1. Name: <span>Martin</span> - nickname: [<span></span>]</p>

  <p>2a. <span>&lt;b&gt;this is HTML&lt;/b&gt;</span></p>
  <p>2b. <span><b>this is HTML</b></span></p>

  <p>3. You are logged in.</p>


  <p>4. Our products:</p>
  <ul>
    <li>no. 0: Keyboard, 25 €
      <span>(in stock)</span>
      - the first one

    </li>
    <li>no. 1: Mouse, 12.5 €
      <span>(sold out)</span>


    </li>
    <li>no. 2: Screen, 149 €
      <span>(in stock)</span>

      - the last one, seen by Martin
    </li>
  </ul>

  <p>5. Your cart:
    it is empty.

  </p>

  <p>6. 3 products, for a total of 186.5 €; average price: 62.17 €</p>
  <p>7. Address: 12 rue des Lilas, ANGERS</p>
  <p>8. Um endereço de e-mail: contact@example.com</p>
</body>
</html>

Observe que:

  • as tags [th:block], os comentários [Thymeleaf] e as tags removidas por [th:if] / [th:unless] deixam linhas em branco que não têm efeito sobre a exibição;
  • O preço médio é [62.17] no [curl] e [62,17] no navegador. [#numbers.formatDecimal] usa o idioma da requisição. Por padrão, o [Spring MVC] o lê do cabeçalho HTTP [Accept-Language] enviado pelo navegador: um navegador configurado em francês envia [Accept-Language: fr-FR] e recebe uma vírgula; [curl] não envia esse cabeçalho, e o idioma passa a ser o do sistema em que o servidor está sendo executado (neste caso, o inglês; em um computador configurado em francês, o [curl] também receberia uma vírgula). O Exemplo 16 e o capítulo “Internacionalização” tratam desse mecanismo;
  • os próprios preços ([12.5]) são gerados pelo método [toString] de [BigDecimal], que independe do idioma. O Exemplo 16 os formata.

Para concluir este exemplo, aqui estão os cinco tipos de expressões do [Thymeleaf], que serão usados nos exemplos deste capítulo e do próximo:

Expressão
Função
Exemplo
[${...}]
expressão de variável ([SpEL]): um atributo do modelo, uma propriedade, uma chamada de método, um bean ([${@name...}]), um objeto utilitário ([${#strings...}])
13, 14, 16
[*{...}]
expressão de seleção: uma propriedade do objeto designado pelo atributo [th:object]
18, 19, 21
[#{...}]
mensagem: texto do arquivo [messages.properties], no idioma da requisição
Próximo capítulo
[@{...}]
link: uma URL, com suas variáveis e parâmetros
16, 21
[~{...}]
fragmento: uma seção de página a ser inserida
15 a 21

Existem inúmeros objetos utilitários: [#strings], [#numbers], [#lists], [#aggregates], [#dates] (datas [java.util.Date]), [#temporals] (datas [java.time]: [LocalDate], [LocalDateTime]...), [#locale] (o idioma da requisição), [#ids], e [#fields] (formulários, exemplos 18 e 19)... A documentação do [Thymeleaf] (https://www.thymeleaf.org) descreve todos eles.

4.3. Exemplo 15: Template, fragmentos, arquivos estáticos

As páginas de um site compartilham um template comum (cabeçalho, barra de navegação, rodapé). Para o [Thymeleaf], os componentes de página reutilizáveis são os fragmentos; e o próprio template é um fragmento, no qual cada página insere seu conteúdo. Por fim, as páginas precisam de arquivos estáticos (folhas de estilo, imagens, scripts), que são servidos como estão, sem passar por um controller. Os arquivos do exemplo:

15-layout/
├── src/
│   └── main/
│       ├── java/
│       │   └── example15/
│       │       ├── config/
│       │       │   ├── CommonModel.java
│       │       │   └── WebConfig.java
│       │       ├── controllers/
│       │       │   └── PagesController.java
│       │       └── Example15Application.java
│       └── resources/
│           ├── static/
│           │   └── css/
│           │       └── styles.css
│           ├── templates/
│           │   ├── fragments/
│           │   │   ├── card.html
│           │   │   └── navbar.html
│           │   ├── pages/
│           │   │   ├── home.html
│           │   │   ├── raw.html
│           │   │   └── team.html
│           │   └── layout.html
│           └── application.properties
└── pom.xml

4.3.1. Os arquivos estáticos

O [Spring Boot] serve automaticamente, sem controller, os arquivos da pasta de recursos [static] : O arquivo [src/main/resources/static/css/styles.css] é servido na URL [/css/styles.css]. Se nenhum arquivo corresponder à URL e nenhuma action a tratar, a resposta é um 404. Vamos verificar:

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: 430

/* alguns ajustes sobre o Bootstrap */
body {
  background-color: #f5f7fa;
}

/* o rodapé do layout */
.footer {
  margin-top: 2rem;
  font-size: 0.85rem;
  color: #6c757d;
}

/* as mensagens de erro, no final da página, sobre um fundo rosa claro */
.error-area {
  margin-top: 1.5rem;
  padding: 0.75rem 1rem;
  background-color: #fdecef;
  border: 1px solid #f5c2c7;
  border-radius: 0.375rem;
  color: #842029;
}

O cabeçalho [Last-Modified] informa a data de modificação do arquivo: o navegador só solicitará o arquivo novamente, enviando essa data de volta, se ele tiver sido alterado.

O framework CSS [Bootstrap] é comum a todos os exemplos: ele é armazenado uma única vez, na pasta [examples/common/bootstrap], fora dos recursos dos exemplos. É preciso, portanto, informar ao [Spring MVC] onde encontrá-lo. O arquivo [config/WebConfig.java]:

package example15.config;

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

// a configuração do Spring MVC, complementada
@Configuration
public class WebConfig implements WebMvcConfigurer {

    // Bootstrap, compartilhado pelos exemplos: a pasta examples/common/bootstrap
    // é servida na URL /bootstrap/...
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/bootstrap/**")
                // "file:": uma pasta do disco, relativa à pasta atual. Duas
                // tentativas: iniciado a partir da pasta do exemplo, ou a partir de [examples]
                .addResourceLocations("file:../common/bootstrap/", "file:common/bootstrap/");
    }
}

Vamos comentar este código:

  • linha 8: uma classe de configuração (veja o Exemplo 06);
  • linha 9: a interface [WebMvcConfigurer] nos permite complementar a configuração do [Spring MVC] criada pelo [Spring Boot], sem substituí-la: redefinimos apenas os métodos que nos interessam (todos os outros têm uma implementação padrão, vazia);
  • linhas 14–19: O método [addResourceHandlers] declara diretórios de arquivos estáticos. Os arquivos da URL que começam com [/bootstrap/] (linha 15; [**] designa qualquer sequência de diretórios e arquivos) são servidos a partir do diretório [common/bootstrap];
  • linha 18: o prefixo [file:] designa uma pasta no disco (e não no classpath). O caminho é relativo ao diretório atual, aquele a partir do qual a aplicação foi iniciada: [../common/bootstrap/] se iniciada a partir do diretório do exemplo, [common/bootstrap/] se iniciada a partir do diretório [examples]. Os dois locais são verificados em ordem. Assim, [examples/common/bootstrap/css/bootstrap.min.css] é servido na URL [/bootstrap/css/bootstrap.min.css]. O estudo de caso, por sua vez, coloca o [Bootstrap] em sua própria pasta, [static].

Todos os exemplos a seguir usam este arquivo: [WebConfig.java].

4.3.2. O template

O arquivo [templates/layout.html]:

<!doctype html>
<!--/* o layout das páginas: um fragmento com dois parâmetros, o título da
       página e seu conteúdo (ele próprio um fragmento, fornecido pela página) */-->
<html lang="en" xmlns:th="http://www.thymeleaf.org" th:fragment="page(title, content)">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title th:text="|${title} - My site|">My 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">
    <!--/* inserção do fragmento [navbar] do arquivo fragments/navbar.html */-->
    <nav th:replace="~{fragments/navbar :: navbar}"></nav>
    <!--/* o conteúdo da página solicitada pela ação é inserido aqui */-->
    <main th:replace="${content}"></main>
    <!--/* path: adicionado ao modelo de todas as views (veja config/CommonModel.java) */-->
    <footer class="footer" th:text="|Page [${path}] - © ${#dates.year(#dates.createNow())}|">footer</footer>
  </div>
</body>
</html>

Vamos analisar este código:

  • Linha 4: O atributo [th:fragment] transforma a tag [<html>], e portanto a página inteira, em um fragmento chamado [page], que espera dois parâmetros: [title] e [content]. As páginas da aplicação chamarão esse fragmento, passando a ele seu título e seu conteúdo;
  • linha 8: o parâmetro [title] é usado como um atributo do modelo;
  • linhas 9–10: as folhas de estilo, servidas como arquivos estáticos;
  • linha 15: o atributo [th:replace] substitui a tag que o contém (aqui, [<nav>]) por um fragmento. [~{fragments/navbar :: navbar}] é uma expressão de fragmento: o fragmento [navbar] do arquivo [templates/fragments/navbar.html] (à esquerda de [::], o nome da view; à direita, o nome do fragmento);
  • linha 17: o local onde o conteúdo da página, recebido no parâmetro [content], é inserido; esse parâmetro é ele próprio um fragmento, que [th:replace] insere no lugar da tag [<main>];
  • linha 19: [path] é o caminho da página solicitada. Este não é um parâmetro do fragmento: é um atributo adicionado ao modelo de todas as views por uma classe que veremos mais adiante. [#dates.createNow()] é a data atual, e [#dates.year] extrai o ano dela.

Existe um segundo atributo de inserção, [th:insert], que insere o fragmento dentro da tag hospedeira em vez de substituí-la. Com um fragmento [<span th:fragment="f">...</span>], escrever [<div th:replace="~{:: f}"></div>] produz [<span>...</span>], e [<div th:insert="~{:: f}"></div>] produz [<div><span>...</span></div>] ([~{:: f}], sem nome de view, refere-se a um fragmento da view atual). Os exemplos deste curso usam [th:replace].

O arquivo [templates/fragments/navbar.html]:

1
2
3
4
5
6
7
8
9
<!--/* um arquivo de fragmentos: cada tag th:fragment é um pedaço de página reutilizável */-->
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3" th:fragment="navbar">
  <span class="navbar-brand">My site</span>
  <div class="navbar-nav">
    <a class="nav-link" href="/">Home</a>
    <a class="nav-link" href="/team">Team</a>
    <a class="nav-link" href="/raw">Page without layout</a>
  </div>
</nav>
  • Linha 2: Um arquivo de fragmentos não é uma página completa; ele contém uma ou mais tags com o atributo [th:fragment]. Este fragmento não tem parâmetros. Observe que o arquivo não declara o namespace [xmlns:th]; isso não é necessário.

O arquivo [templates/fragments/card.html]:

1
2
3
4
5
6
7
<!--/* um "card" do Bootstrap; seus dois parâmetros: um nome e um papel */-->
<div class="card" th:fragment="card(name, role)">
  <div class="card-body">
    <h5 class="card-title" th:text="${name}">Name</h5>
    <p class="card-text" th:text="${role}">Role</p>
  </div>
</div>
  • Linha 2: O fragmento [card] tem dois parâmetros, um nome e uma função;
  • linhas 4–5: os parâmetros são usados como atributos do modelo.

4.3.3. As páginas

O arquivo [controllers/PagesController.java]:

package example15.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 {

    // um membro da equipe
    public record Member(String name, String role) {
    }

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

    @GetMapping("/team")
    public String team(Model model) {
        List<Member> members = List.of(
                new Member("Marie Pélissier", "Director"),
                new Member("Jacques Bromard", "Developer"),
                new Member("Philippe Jandot", "Graphic designer"));
        model.addAttribute("members", members);
        return "pages/team";
    }

    @GetMapping("/raw")
    public String raw() {
        return "pages/raw";
    }
}
  • Linhas 13–14: o tipo dos membros da equipe, um record declarado no controller ([PagesController.Member]);
  • linhas 17–19: a action [home] não tem modelo; ela não exige o parâmetro [Model];
  • linhas 22–28: a action [team] passa uma lista de membros.

O arquivo [templates/pages/home.html]:

<!doctype html>
<!--/* a página inteira é SUBSTITUÍDA pelo fragmento [page] do layout, ao qual
       passamos o título e o fragmento [main] desta página (~{::main}) */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page('Home', ~{::main})}">
<body>
<main>
  <h1>Welcome</h1>
  <p>This page only contains its own content: the header, the navigation
    bar and the footer come from the <code>layout.html</code> layout.</p>
  <!--/* o fragmento [card], com dois parâmetros escritos na hora */-->
  <div th:replace="~{fragments/card :: card('A fragment', 'inserted with parameters written on the spot')}"></div>
</main>
</body>
</html>

Vamos analisar este código:

  • linha 4: o atributo [th:replace] da tag [<html>] substitui a página inteira pelo fragmento [page] do template [layout.html]. Ele lhe passa dois parâmetros: o título, uma string literal entre aspas simples, e o conteúdo, [~{::main}]. Essa expressão de fragmento, que não tem nome de view, refere-se a uma tag da view atual: neste caso, a tag [<main>] (linhas 6–12). O template é assim gerado, com a tag da página substituindo a sua própria tag, [<main>];
  • linha 11: a chamada ao fragmento [card], com dois parâmetros definidos diretamente.

Tudo o que está na página fora da tag [<main>] (a tag [<body>], por exemplo) desaparece: só importa o fragmento passado ao template. As tags [<html>] e [<body>] são incluídas unicamente para garantir que o arquivo continue sendo uma página HTML válida, que pode ser aberta em um navegador.

O arquivo [templates/pages/team.html]:

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page('Our team', ~{::main})}">
<body>
<main>
  <h1>Our team</h1>
  <div class="row g-3">
    <div class="col-md-4" th:each="member : ${members}">
      <!--/* o fragmento recebe o nome e o papel do membro atual */-->
      <div th:replace="~{fragments/card :: card(${member.name}, ${member.role})}"></div>
    </div>
  </div>
</main>
</body>
</html>
  • linha 7: a tag [<div class="col-md-4">] é repetida para cada membro;
  • linha 9: o fragmento recebe o nome e o papel do membro atual: a tag marcada com [th:replace] está aninhada na marcada com [th:each], em que a variável [member] é definida.

O arquivo [templates/pages/raw.html]:

<!doctype html>
<!--/* esta view não usa o layout: é uma página completa */-->
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Raw page</title>
</head>
<body>
  <p>This page does not use the layout: no Bootstrap, no navigation bar.</p>
  <p><a href="/">Back to home</a></p>
</body>
</html>
  • Linhas 3–11: Esta view não chama o template; é uma página completa, sem atributos [th:]. O [Thymeleaf] a copia como está (exceto pelo comentário da linha 2). Não há obrigação de uma view usar o template.

O código HTML da página http://localhost:5000/team mostra o resultado da montagem:

curl http://localhost:5000/team
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Our team - My 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">My site</span>
  <div class="navbar-nav">
    <a class="nav-link" href="/">Home</a>
    <a class="nav-link" href="/team">Team</a>
    <a class="nav-link" href="/raw">Page without layout</a>
  </div>
</nav>

    <main>
  <h1>Our team</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">Director</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">Developer</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">Graphic designer</p>
  </div>
</div>
    </div>
  </div>
</main>

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

O título, a barra de navegação, três cartões e o rodapé foram montados a partir de quatro arquivos: [layout.html], [navbar.html], [team.html], and [card.html].

4.3.4. Um atributo comum a todas as views

O rodapé do template exibe o caminho da página solicitada, [path]. Com o [Razor], uma view tem acesso direto à requisição atual. Uma view [Thymeleaf] também podia fazer isso, até a versão 3.0, usando o objeto [#request]: teria sido escrito [${#request.requestURI}]. Isso não vale mais a partir da versão 3.1. Uma view que usa [#request] causa um erro 500, e o console exibe:

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.

Os objetos [#request], [#session], [#servletContext], e [#response] foram removidos: eles permitiam que uma view lesse qualquer parâmetro da requisição, o que abria caminho para injeções, e vinculavam o [Thymeleaf] à API de servlets. A entrada [${#ctx.request.requestURI}] também não funciona: [#ctx.request] é igual a [null]. A mensagem de erro indica a solução: adicionar ao modelo o que a view precisa. Para que isso valha para todas as views sem que cada action precise fazê-lo, criamos o arquivo [config/CommonModel.java]:

package example15.config;

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

import jakarta.servlet.http.HttpServletRequest;

// @ControllerAdvice: esta classe complementa TODOS os controllers da aplicação
@ControllerAdvice
public class CommonModel {

    // @ModelAttribute: executado antes de cada ação, este método adiciona ao
    // modelo de todas as views o atributo [path], o caminho da página solicitada
    @ModelAttribute("path")
    public String path(HttpServletRequest request) {
        return request.getRequestURI();
    }
}

Vamos comentar este código:

  • linha 9: a anotação [@ControllerAdvice] designa uma classe que estende todos os controllers da aplicação. O que ela declara se aplica a cada um deles, como se estivesse escrito em cada um;
  • linha 14: um método anotado com [@ModelAttribute("path")] é executado antes de cada action; seu valor de retorno é adicionado ao modelo com o nome [path]. Quando escrito em um controller, aplica-se às actions desse controller (veja o Exemplo 18); quando escrito em uma classe [@ControllerAdvice], aplica-se a todas as actions da aplicação;
  • Linhas 15–16: O método pode aceitar os mesmos parâmetros que uma action: neste caso, a requisição atual, [HttpServletRequest] (veja o Exemplo 05). [getRequestURI()] devolve o caminho solicitado, sem os parâmetros.

O estudo de caso usa o mesmo processo (seu arquivo [web/CommonModel.java]) para fornecer a todas as suas views o caminho, o idioma e o usuário conectado.

As páginas resultantes, na URL http://localhost:5000/, http://localhost:5000/team e http://localhost:5000/raw:

Image

Image

Image

O template, os fragmentos e o atributo comum [path] são exatamente o que o estudo de caso usa: um template [layout.html], fragmentos para a barra de navegação, as mensagens e as janelas de confirmação.

4.4. Exemplo 16: Helpers

Uma view costuma precisar de pequenas funções de formatação: formatar uma data ou um preço, colocar um texto em maiúsculas, criar o HTML de um badge... Elas são chamadas de helpers. Com o [Thymeleaf], são métodos de beans do [Spring], chamados dentro de uma expressão ou de um fragmento. O [Thymeleaf] também permite criar seus próprios atributos, agrupados em um dialeto.

4.4.1. Um bean chamado pelas views

O arquivo [helpers/Formats.java]:

package example16.helpers;

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"): um bean chamado [formats], que as views chamam
// com ${@formats.money(...)}
@Component("formats")
public class Formats {

    // "keyboard" -> "KEYBOARD"; Locale.ROOT: o resultado não depende do idioma
    public String uppercase(String text) {
        return text == null ? "" : text.toUpperCase(Locale.ROOT);
    }

    // um valor em uma moeda, no formato do idioma da requisição
    public String money(BigDecimal amount, String currency) {
        // o idioma da requisição atual, definido pelo LocaleResolver (veja WebConfig)
        Locale language = LocaleContextHolder.getLocale();
        NumberFormat format = NumberFormat.getCurrencyInstance(language);
        format.setCurrency(Currency.getInstance(currency));
        return format.format(amount);
    }

    // o mesmo, em euros
    public String money(BigDecimal amount) {
        return money(amount, "EUR");
    }

    // uma data por extenso, no idioma da requisição: "Friday, September 25, 2026"
    public String date(LocalDate day) {
        return day.format(DateTimeFormatter.ofLocalizedDate(FormatStyle.FULL).withLocale(LocaleContextHolder.getLocale()));
    }
}

Vamos comentar este código:

  • Linha 16: a anotação [@Component] transforma a classe em um bean: o [Spring] a encontra na inicialização (assim como encontra os controllers), cria uma instância dela e a mantém. ["formats"] é o nome do bean: é o nome que as views usarão para chamá-lo;
  • linhas 20 a 22: colocar em maiúsculas. [Locale.ROOT] torna o resultado independente do idioma do usuário;
  • linhas 25 a 31: um valor em uma moeda, formatado de acordo com o idioma da requisição. [LocaleContextHolder.getLocale()] (linha 27) obtém esse idioma, um objeto [Locale] definido pelo [Spring MVC] no início de cada requisição. [NumberFormat.getCurrencyInstance] fornece o formato de moeda desse idioma: separador decimal, separador de milhares e posição do símbolo da moeda; [setCurrency] seleciona a moeda, identificada por seu código internacional ([EUR], [USD]);
  • linhas 34 a 36: um método sobrecarregado: mesmo nome, parâmetros diferentes. Se nenhuma moeda for especificada, o padrão é o euro;
  • linhas 39 a 41: uma data por extenso ([FormatStyle.FULL]), no idioma da requisição.

A página [templates/pages/products.html] chama esses métodos:

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page('Products', ~{::main})}">
<body>
<main>
  <h1>Products</h1>
  <table class="table table-sm w-auto">
    <thead><tr><th>Product</th><th>Price</th><th>Price in dollars</th><th>Stock</th></tr></thead>
    <tbody>
      <tr th:each="product : ${products}">
        <td th:text="${@formats.uppercase(product.name)}">KEYBOARD</td>
        <td th:text="${@formats.money(product.price)}">€25.00</td>
        <td th:text="${@formats.money(product.price, 'USD')}">$25.00</td>
        <!--/* o fragmento [badge] constrói o HTML do badge */-->
        <td><span th:replace="~{fragments/badge :: badge(${product.stock})}">badge</span></td>
      </tr>
    </tbody>
  </table>
</main>
</body>
</html>
  • linhas 10 a 12: em uma expressão [${...}], a notação [@formats] refere-se ao bean chamado [formats]: [${@formats.money(product.price)}] chama seu método [money]. O valor de retorno do método é inserido por [th:text] e, portanto, passa por escape;
  • Linha 14: o badge é criado por um fragmento, descrito a seguir.

O arquivo [templates/fragments/badge.html]:

1
2
3
4
5
<!--/* um badge do Bootstrap: verde se o produto estiver em estoque, vermelho caso contrário.
       Um fragmento é a forma do Thymeleaf de construir um trecho de HTML reutilizável */-->
<span class="badge" th:fragment="badge(stock)"
      th:classappend="${stock > 0} ? 'text-bg-success' : 'text-bg-danger'"
      th:text="${stock > 0} ? |${stock} in stock| : 'sold out'">12 in stock</span>
  • linha 3: um helper que gera HTML é, no [Thymeleaf], um fragmento: neste caso, uma tag [<span>] que recebe o estoque do produto como parâmetro;
  • linha 4: o atributo [th:classappend] adiciona uma classe CSS às classes já existentes da tag ([badge]): verde ([text-bg-success]) se o produto estiver em estoque, vermelho caso contrário;
  • linha 5: o texto do badge, com escape feito por [th:text]. Ao contrário de um helper que geraria HTML em uma string, um fragmento não precisa se preocupar com o escape: o [th:text] cuida disso.

O controller, arquivo [controllers/PagesController.java]:

package example16.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 Product(String name, BigDecimal price, int stock) {
    }

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

    @GetMapping("/products")
    public String products(Model model) {
        model.addAttribute("products", List.of(
                new Product("keyboard", new BigDecimal("25"), 12),
                new Product("mouse", new BigDecimal("12.5"), 0),
                new Product("screen", new BigDecimal("1149.9"), 3)));
        return "pages/products";
    }
}
  • linha 19: a página inicial recebe a data de hoje, um [LocalDate] (uma data sem hora);
  • linhas 25 a 28: a lista de produtos.

O arquivo [templates/pages/home.html]:

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page('Home', ~{::main})}">
<body>
<main>
  <h1>Home</h1>
  <!--/* @formats: o bean chamado [formats]; chamamos seu método date */-->
  <p th:text="|Today is ${@formats.date(today)}.|">Today is...</p>
  <!--/* #locale: o idioma da requisição */-->
  <p>Formatting language: <span th:text="${#locale}">en_US</span>
    (<a href="/?lang=fr">in French</a>, <a href="/">in English</a>)</p>
</main>
</body>
</html>
  • linha 7: a chamada ao método [date] do bean [formats], em uma substituição literal;
  • linha 9: o objeto utilitário [#locale] é o idioma da requisição.

4.4.2. O idioma da requisição

O que determina o idioma da requisição? Um bean do [Spring MVC], o resolvedor de idioma ([LocaleResolver]). O que o [Spring Boot] instala por padrão, [AcceptHeaderLocaleResolver], lê o cabeçalho [Accept-Language] enviado pelo navegador: foi isso que causou resultados diferentes para o navegador e para o [curl] no Exemplo 14. Para facilitar o teste dos dois idiomas, o Exemplo 16 o substitui por um resolvedor que lê o parâmetro [lang] da URL. O arquivo [config/WebConfig.java]:

package example16.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 example16.helpers.ActiveDialect;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

// a configuração do Spring MVC, complementada
@Configuration
public class WebConfig implements WebMvcConfigurer {

    // Bootstrap, compartilhado pelos exemplos: a pasta examples/common/bootstrap
    // é servida na URL /bootstrap/...
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/bootstrap/**")
                // "file:": uma pasta do disco, relativa à pasta atual. Duas
                // tentativas: iniciado a partir da pasta do exemplo, ou a partir de [examples]
                .addResourceLocations("file:../common/bootstrap/", "file:common/bootstrap/");
    }

    // nosso dialeto Thymeleaf (o atributo ex:active), adicionado à engine de views
    @Bean
    public ActiveDialect activeDialect() {
        return new ActiveDialect();
    }

    // o idioma de formatação de cada requisição: o parâmetro ?lang=fr da URL,
    // inglês caso contrário. O bean deve se chamar [localeResolver]: é com este
    // nome que o Spring MVC o procura.
    @Bean
    public LocaleResolver localeResolver() {
        return new LanguageParameterResolver();
    }

    // um LocaleResolver define o idioma (Locale) de cada requisição; o Spring o armazena
    // em LocaleContextHolder, onde as views e os helpers o reencontram
    static class LanguageParameterResolver implements LocaleResolver {

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

        @Override
        public void setLocale(HttpServletRequest request, HttpServletResponse response, Locale locale) {
            throw new UnsupportedOperationException("the language is set by the URL");
        }
    }
}

Vamos comentar este código:

  • linhas 21 a 27: os arquivos do [Bootstrap], como no Exemplo 15;
  • linhas 30 a 33: nosso dialeto do [Thymeleaf], descrito a seguir, declarado como um bean. O [Spring Boot] adiciona automaticamente ao engine do [Thymeleaf] todos os beans que são dialetos;
  • linhas 38 a 41: nosso resolvedor de idioma. O bean deve se chamar [localeResolver]: é o nome com o qual o [Spring MVC] o procura. O nome do método anotado com [@Bean] fornece o nome do bean: [localeResolver()]. Ao declarar este bean, substituímos aquele do [Spring Boot];
  • linhas 45 a 56: o resolvedor é uma classe aninhada que implementa a interface [LocaleResolver];
  • linhas 48 a 50: o método [resolveLocale] é chamado no início de cada requisição: ele retorna o francês ([Locale.FRANCE]) se a URL contiver [lang=fr]; caso contrário, retorna o inglês dos EUA ([Locale.US]). O [Spring MVC] armazena esse idioma em [LocaleContextHolder], de onde ele é obtido pelo bean [formats] e pelos objetos utilitários do [Thymeleaf];
  • linhas 53 a 55: o método [setLocale] permitiria alterar o idioma (armazenando-o, por exemplo, em um cookie). Aqui, o idioma vem da URL: o método se recusa a funcionar lançando uma exceção.

Esta é uma forma simples de testar; o próximo capítulo tratará do assunto com mais profundidade.

4.4.3. Um dialeto do Thymeleaf

A barra de navegação destaca o link da página atual (classe CSS [active] do [Bootstrap]). O arquivo [templates/fragments/navbar.html] mostra três maneiras de escrever links:

<!--/* xmlns:ex: o namespace do nosso dialeto (útil somente para os editores) */-->
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3" th:fragment="navbar"
     xmlns:th="http://www.thymeleaf.org" xmlns:ex="http://example16">
  <span class="navbar-brand">Helpers</span>
  <div class="navbar-nav">
    <!--/* 1. uma condição escrita na view (path: veja config/CommonModel.java) */-->
    <a class="nav-link" th:classappend="${path == '/'} ? 'active'" href="/">Home</a>
    <!--/* 2. nosso dialeto: o atributo ex:active="..." */-->
    <a class="nav-link" href="/products" ex:active="/products">Products</a>
    <!--/* 3. uma expressão de link @{...}: o Spring constrói a URL, com seus parâmetros */-->
    <a class="nav-link" th:href="@{/products(lang=fr)}">Produits (fr)</a>
  </div>
</nav>

Vamos detalhar este código:

  • linha 3: o namespace [xmlns:ex], assim como [xmlns:th], destina-se apenas aos editores;
  • linha 7: a primeira maneira de destacar o link da página atual: uma condição escrita na view, usando o atributo [path] fornecido pela classe [CommonModel] (idêntica à do Exemplo 15). Sem a cláusula “else”, o operador condicional não produz nada quando a condição é falsa e, portanto, o [th:classappend] não adiciona nenhuma classe. Este é o método usado no estudo de caso;
  • linha 9: segunda abordagem, mais concisa: um atributo “home”, [ex:active], fornecido por nosso dialeto;
  • linha 11: uma expressão de link [@{...}]. O [Spring] gera a URL: os parênteses contêm parâmetros, que são adicionados à URL ([?lang=fr]). Veremos no Exemplo 21 que eles também servem para preencher variáveis de caminho. Uma expressão de link também adiciona, se necessário, o caminho base da aplicação quando ela não está instalada na raiz do servidor.

Um dialeto é um conjunto de atributos (ou tags) que compartilham um prefixo: os atributos [th:] são os do dialeto padrão do [Thymeleaf]. Cada atributo é processado por um processador. O arquivo [helpers/ActiveDialect.java]:

package example16.helpers;

import java.util.Set;

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

// um DIALETO Thymeleaf: um conjunto de atributos "caseiros", todos prefixados com
// [ex:] (ex:active="..."). Declarado como um bean (veja WebConfig), ele é adicionado
// automaticamente à engine do Thymeleaf pelo Spring Boot.
public class ActiveDialect extends AbstractProcessorDialect {

    public ActiveDialect() {
        // nome do dialeto, prefixo de seus atributos, precedência (a dos atributos th:)
        super("Active", "ex", StandardDialect.PROCESSOR_PRECEDENCE);
    }

    // os "processadores" do dialeto: um só, para o atributo ex:active
    @Override
    public Set<IProcessor> getProcessors(String prefix) {
        return Set.of(new ActiveProcessor(prefix));
    }
}
  • linha 12: um dialeto que fornece apenas processadores deriva da classe [AbstractProcessorDialect];
  • linha 16: o nome do dialeto, o prefixo de seus atributos ([ex]) e sua prioridade: a mesma dos atributos [th:];
  • linhas 21 a 23: os processadores do dialeto: apenas um, o do atributo [ex:active]. [Set.of(...)] cria um conjunto imutável.

O arquivo [helpers/ActiveProcessor.java]:

package example16.helpers;

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;

// o processador do atributo ex:active: <a href="/products" ex:active="/products">
// recebe a classe "active" se a página atual estiver sob este caminho
public class ActiveProcessor extends AbstractAttributeTagProcessor {

    public ActiveProcessor(String prefix) {
        // HTML; somente tags <a>; atributo [ex:active]; precedência; true: o
        // atributo ex:active é removido da página produzida
        super(TemplateMode.HTML, prefix, "a", false, "active", true, 1000, true);
    }

    // chamado para cada tag <a> que carrega o atributo ex:active
    @Override
    protected void doProcess(ITemplateContext context, IProcessableElementTag tag,
            AttributeName attributeName, String value, IElementTagStructureHandler structure) {
        // o caminho da página, lido da requisição atual
        String path = context instanceof IWebContext web ? web.getExchange().getRequest().getRequestPath() : "";
        boolean isActive = value.equals("/") ? path.equals("/") : path.startsWith(value);
        if (isActive) {
            // adicionamos a classe "active" ao atributo class da tag
            String classes = tag.getAttributeValue("class");
            structure.setAttribute("class", classes == null ? "active" : classes + " active");
        }
    }
}

Vamos comentar este código:

  • linha 13: um processador de atributo derivado da classe [AbstractAttributeTagProcessor];
  • linha 18: seu construtor descreve o que ele processa: o modo HTML, o prefixo do dialeto, apenas tags [<a>], o atributo [active] (com prefixo: [ex:active]), uma prioridade e [true]: o atributo [ex:active] será removido da página gerada;
  • linhas 23 e 24: o método [doProcess] é chamado para cada tag [<a>] que tenha o atributo [ex:active]. Ele recebe o contexto da view, a tag e o valor do atributo; o objeto [structure] permite modificar a tag;
  • linha 26: o processador é código [Java], não uma expressão de view: ele tem autorização para ler a requisição atual. Quando a view é renderizada para uma requisição web, o contexto é um [IWebContext], que dá acesso à troca de mensagens (a requisição e sua resposta); [getRequestPath()] retorna o caminho solicitado. A expressão [context instanceof IWebContext web] verifica o tipo do contexto e, se for o caso, o armazena na variável [web];
  • linhas 27 a 32: se o caminho da página começar com o valor do atributo, a classe [active] é adicionada ao atributo [class] da tag.

O código HTML da barra de navegação, na URL [/products]:

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

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

    <a class="nav-link active" href="/products">Products</a>

    <a class="nav-link" href="/products?lang=fr">Produits (fr)</a>
  </div>
</nav>

O link “Products” recebeu a classe [active], e o atributo [ex:active] foi removido. A expressão de link produziu [/products?lang=fr]. Observe que o [Thymeleaf] removeu o atributo [xmlns:th], mas não o atributo [xmlns:ex]: ele não reconhece este último. Ele poderia ter sido omitido, já que só é usado pelos editores.

O template [layout.html] é o do Exemplo 15, sem o rodapé (e os títulos das páginas terminam com [- Helpers] em vez de [- My site]). As páginas resultantes, em inglês (http://localhost:5000/, http://localhost:5000/products) e depois em francês (http://localhost:5000/products?lang=fr):

Image

Image

Image

Os preços mudam de formato conforme o idioma: [1 149,90 €] em francês, [€1,149.90] em inglês. Em francês, os dólares são indicados como [$US] para distingui-los de outras moedas (canadense, australiana etc.). O código HTML da tabela, em francês ([/products?lang=fr]):

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

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

        <td><span class="badge text-bg-danger">sold out</span></td>
      </tr>
      <tr>
        <td>SCREEN</td>
        <td>1 149,90 €</td>
        <td>1 149,90 $US</td>

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

e em inglês ([/products]), em que o dólar é escrito simplesmente como [$]:

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

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

        <td><span class="badge text-bg-danger">sold out</span></td>
      </tr>
      <tr>
        <td>SCREEN</td>
        <td>€1,149.90</td>
        <td>$1,149.90</td>

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

Apenas os valores mudaram: o texto dos badges está fixo no fragmento (o próximo capítulo traduzirá os textos).

4.5. Exemplo 17: Um formulário GET

Um formulário HTML enviado pelo método GET coloca seus campos na URL. Este é o método apropriado para uma busca: ele não modifica nada, e a URL resultante pode ser salva nos favoritos ou compartilhada. O estudo de caso o usa para selecionar um médico e uma data.

Os arquivos [models/Book.java] e [models/SearchModel.java] :

1
2
3
4
package example17.models;

public record Book(String title, String author, String genre) {
}
1
2
3
4
5
6
7
package example17.models;

import java.util.List;

// o modelo da view: a entrada (para exibi-la novamente), os gêneros, os resultados
public record SearchModel(String keyword, String genre, List<String> genres, List<Book> results) {
}
  • Linha 6: o modelo da view contém os valores digitados ([keyword], [genre]) para que o formulário possa exibi-los novamente, junto com a lista de gêneros e os resultados.

O arquivo [controllers/BooksController.java]:

package example17.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 example17.models.Book;
import example17.models.SearchModel;

@Controller
public class BooksController {

    private static final List<Book> BOOKS = List.of(
            new Book("Le Rouge et le Noir", "Stendhal", "novel"),
            new Book("Les Fleurs du mal", "Baudelaire", "poetry"),
            new Book("Madame Bovary", "Flaubert", "novel"),
            new Book("Alcools", "Apollinaire", "poetry"),
            new Book("Le Cid", "Corneille", "drama"));

    private static final List<String> GENRES = List.of("novel", "poetry", "drama");

    // GET / e GET /search?keyword=...&genre=...: o formulário E seus resultados
    @GetMapping({ "/", "/search" })
    public String search(@RequestParam(required = false) String keyword,
            @RequestParam(required = false) String genre, Model model) {
        String word = keyword == null ? "" : keyword.trim().toLowerCase(Locale.ROOT);
        List<Book> results = BOOKS.stream()
                .filter(b -> word.isEmpty() || b.title().toLowerCase(Locale.ROOT).contains(word)
                        || b.author().toLowerCase(Locale.ROOT).contains(word))
                .filter(b -> genre == null || genre.isEmpty() || b.genre().equals(genre))
                .toList();
        model.addAttribute("model", new SearchModel(keyword == null ? "" : keyword,
                genre == null ? "" : genre, GENRES, results));
        return "books/search";
    }
}

Vamos detalhar este código:

  • linhas 17 a 24: os livros e os gêneros, em memória;
  • linha 27: uma única ação pode corresponder a vários caminhos; ela trata tanto [GET /] quanto [GET /search];
  • linhas 28 e 29: os parâmetros [keyword] e [genre] são vinculados aos parâmetros de mesmo nome na URL (veja o exemplo 07). [required = false] os torna opcionais: na primeira visita, o formulário ainda não foi enviado, e seus valores são [null];
  • linhas 31 a 35: filtragem, usando um stream ([stream]) [Java] (veja o Exemplo 06): [stream()] percorre a lista; cada [filter] mantém apenas os livros que satisfazem uma condição; e [toList()] reúne os livros selecionados em uma nova lista. As condições são expressões lambda: [b -> ...] é uma função anônima que recebe um livro [b] e retorna um booleano. Uma palavra-chave vazia ou um gênero vazio não filtra nada;
  • linhas 36 e 37: o modelo da view. Aqui, os [null] são substituídos por strings vazias.

O template [templates/layout.html] é simplificado: um único parâmetro, o conteúdo da página, e um título fixo:

<!doctype html>
<html lang="en" xmlns:th="http://www.thymeleaf.org" th:fragment="page(content)">
<head>
  <meta charset="utf-8">
  <title>Books</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="${content}"></main>
  </div>
</body>
</html>
  • linha 2: o fragmento [page] agora tem apenas um parâmetro, [content];
  • Linha 5: o título é o mesmo para todas as páginas.

O arquivo [templates/books/search.html]:

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main>
  <h1 class="h3">Book search</h1>
  <!--/* method="get": os campos são enviados na URL (?keyword=...&genre=...) */-->
  <form method="get" action="/search" class="row g-2 align-items-end mb-3">
    <div class="col-auto">
      <label class="form-label" for="keyword">Title or author</label>
      <!--/* th:value: o campo exibe novamente o que foi digitado */-->
      <input class="form-control" id="keyword" name="keyword" th:value="${model.keyword}">
    </div>
    <div class="col-auto">
      <label class="form-label" for="genre">Genre</label>
      <select class="form-select" id="genre" name="genre">
        <option value="">(all)</option>
        <!--/* th:selected: um atributo booleano, escrito se a condição for verdadeira, omitido caso contrário */-->
        <option th:each="genre : ${model.genres}" th:value="${genre}" th:text="${genre}"
                th:selected="${genre == model.genre}">novel</option>
      </select>
    </div>
    <div class="col-auto">
      <button class="btn btn-primary" type="submit">Search</button>
    </div>
  </form>
  <p th:text="|${#lists.size(model.results)} book(s) found.|">0 book(s) found.</p>
  <ul>
    <li th:each="book : ${model.results}"><i th:text="${book.title}">Title</i>, [[${book.author}]] ([[${book.genre}]])</li>
  </ul>
</main>
</body>
</html>

Vamos detalhar este código:

  • Linha 2: a página passa seu único parâmetro, a tag [<main>], para o template;
  • Linha 7: [method="get"] e [action="/search"]: o envio do formulário é uma requisição [GET /search?keyword=...&genre=...]. Os nomes dos parâmetros são o atributo [name] de cada campo;
  • Linha 11: o atributo [th:value] define o atributo [value] do campo: ele restaura o valor digitado. De modo geral, [th:xxx] calcula o valor dos atributos HTML [xxx]: [th:value], [th:href], [th:action], [th:class]...
  • Linhas 18 e 19: uma opção por gênero. Dentro da mesma tag, [th:each] é processado primeiro, seguido de [th:value] e [th:text], que usam a variável do laço. [th:selected] é um atributo booleano: se a expressão for verdadeira, o [Thymeleaf] escreve [selected="selected"]; se for falsa, ele não escreve o atributo. É exatamente o que o HTML exige; para este atributo, a mera presença do atributo [selected] basta para selecionar a opção. O mesmo vale para [th:checked], [th:disabled], [th:required], [th:readonly]...;
  • linha 26: o número de resultados;
  • linha 28: a lista de resultados, com uma tag [<i>] e duas expressões inline.

O código HTML da lista suspensa, após uma busca como [poetry]:

1
2
3
4
5
6
7
8
9
      <select class="form-select" id="genre" name="genre">
        <option value="">(all)</option>

        <option value="novel">novel</option>

        <option value="poetry" selected="selected">poetry</option>

        <option value="drama">drama</option>
      </select>

Na exibição inicial (http://localhost:5000/) e depois de uma busca:

Image

Image

A barra de endereços mostra os parâmetros que foram enviados. Aqui eles contêm apenas letras simples; caracteres especiais seriam codificados ali (um [é] acentuado se torna [%C3%A9], por exemplo): é a codificação de URL, que o [Spring MVC] decodifica antes de os parâmetros serem concatenados.

4.6. Exemplo 18: Campos de formulário

O Exemplo 18 combina todos os tipos de campos HTML: texto, senha, data, botões de opção, caixas de seleção, lista suspensa, lista de seleção múltipla, caixa de texto e campo oculto. Ele mostra como o servidor os recebe e como a view os exibe. Também apresenta o atributo [th:field], que vincula um campo de formulário a uma propriedade de um objeto do modelo.

O arquivo [services/ListsService.java]:

package example18.services;

import java.util.List;

import org.springframework.stereotype.Service;

// as listas oferecidas pelo formulário. Em uma aplicação real, elas
// viriam de um banco de dados: seriam lidas UMA VEZ, na inicialização,
// já que são as mesmas para todos os usuários.
// @Service: um bean (singleton), encontrado pelo Spring como os controllers
@Service
public class ListsService {

    public record Country(String code, String name) {
    }

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

    public List<Country> getCountries() {
        return List.of(new Country("fr", "France"), new Country("be", "Belgium"), new Country("ch", "Switzerland"),
                new Country("ca", "Canada"));
    }

    public List<String> getHobbies() {
        return List.of("reading", "music", "sport", "cinema");
    }

    public List<String> getLanguages() {
        return List.of("French", "English", "Spanish", "German");
    }
}
  • Linha 11: a anotação [@Service] transforma a classe em um bean, assim como [@Component] (Exemplo 16): o [Spring] a encontra na inicialização e cria uma única instância dela, um singleton (veja o Exemplo 06), que pode ser injetado nos controllers. [@Service] difere de [@Component] apenas pela intenção que expressa: a classe é um serviço. As listas fornecidas pelo formulário são as mesmas para todos os usuários: um singleton é o lugar natural para armazená-las;
  • linhas 14 e 15: um país, ou seja, um código e um nome;
  • linhas 17 a 32: as listas, retornadas pelos métodos [getXxx()]. Para uma view, essas são as propriedades do bean [titles], [countries], [hobbies] e [languages] : [${lists.titles}] chamará [getTitles()].

O arquivo [models/Input.java]:

package example18.models;

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

import org.springframework.format.annotation.DateTimeFormat;

// o que o usuário digitou: o binding de modelo preenche cada campo
// com o parâmetro de mesmo nome (as listas recebem todos os valores marcados)
public class Input {

    private String name;
    private String password;
    private String comment;
    private String title;
    private List<String> hobbies = new ArrayList<>();
    private String country;
    private List<String> languages = new ArrayList<>();
    // um campo <input type="date"> envia a data no formato ISO: yyyy-mm-dd
    @DateTimeFormat(iso = DateTimeFormat.ISO.DATE)
    private LocalDate birthDate;
    private String token;

    public String getName() { return name; }
    public void setName(String name) { this.name = name; }

    public String getPassword() { return password; }
    public void setPassword(String password) { this.password = password; }

    public String getComment() { return comment; }
    public void setComment(String comment) { this.comment = comment; }

    public String getTitle() { return title; }
    public void setTitle(String title) { this.title = title; }

    public List<String> getHobbies() { return hobbies; }
    public void setHobbies(List<String> hobbies) { this.hobbies = hobbies; }

    public String getCountry() { return country; }
    public void setCountry(String country) { this.country = country; }

    public List<String> getLanguages() { return languages; }
    public void setLanguages(List<String> languages) { this.languages = languages; }

    public LocalDate getBirthDate() { return birthDate; }
    public void setBirthDate(LocalDate birthDate) { this.birthDate = birthDate; }

    public String getToken() { return token; }
    public void setToken(String token) { this.token = token; }
}

Vamos comentar este código:

  • Linhas 13 a 23: a entrada é uma classe [JavaBean] (campos privados, um construtor sem parâmetros e os acessores [getXxx] e [setXxx]), e não um record: o binding do modelo a cria vazia e depois preenche cada propriedade com o parâmetro de mesmo nome, por meio de seu setter [setXxx];
  • linhas 17 e 19: as caixas de seleção e a lista de seleção múltipla são listas: elas recebem todos os valores enviados (veja o Exemplo 10). São inicializadas com uma lista vazia, nunca com [null];
  • Linhas 21 e 22: um campo [<input type="date">] envia a data no formato [ISO 8601] [yyyy-mm-dd]. A anotação [@DateTimeFormat(iso = DateTimeFormat.ISO.DATE)] especifica esse formato para o [Spring], que o usa nos dois sentidos: para converter o texto recebido em [LocalDate] e para reescrever a data no campo.

O arquivo [controllers/FormController.java]:

package example18.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 example18.models.Input;
import example18.services.ListsService;
import jakarta.servlet.http.HttpServletRequest;

@Controller
@RequestMapping("/form")
public class FormController {

    private final ListsService lists;

    public FormController(ListsService lists) {
        this.lists = lists;
    }

    // @ModelAttribute em um método: executado antes de CADA ação deste
    // controller, ele adiciona o atributo [lists] ao modelo
    @ModelAttribute("lists")
    public ListsService lists() {
        return lists;
    }

    // GET: o formulário, com valores iniciais
    @GetMapping("")
    public String display(Model model) {
        Input initial = new Input();
        initial.setTitle("Mme");
        initial.setCountry("fr");
        initial.setLanguages(List.of("French"));
        initial.setToken("A7X2");
        model.addAttribute("input", initial);
        return "form/form";
    }

    // POST: o binding de modelo preenche [input], adicionado ao modelo sob o nome
    // "input" (o nome de sua classe, com a primeira letra minúscula); nós o exibimos novamente
    @PostMapping("")
    public String process(@ModelAttribute Input input, HttpServletRequest request, Model model) {
        // o que o navegador realmente enviou, parâmetro por parâmetro
        Map<String, String[]> parameters = request.getParameterMap();
        String received = parameters.entrySet().stream()
                .map(p -> p.getKey() + " = [" + String.join(", ", p.getValue()) + "]")
                .collect(Collectors.joining("\n"));
        model.addAttribute("received", received);
        return "form/form";
    }
}

Vamos detalhar este código:

  • linhas 22 a 26: o serviço de listas é injetado pelo construtor (veja o Exemplo 06);
  • linhas 30 a 33: um método anotado com [@ModelAttribute("lists")], declarado em um controller, é executado antes de cada ação desse controller: as duas ações encontrarão o atributo [lists] em seu modelo, sem precisar adicioná-lo (veja [CommonModel], Exemplo 15, para todas as ações da aplicação);
  • linhas 36 a 45: [GET /form] exibe o formulário com valores iniciais. O objeto é armazenado no modelo com o nome [input];
  • linha 50: [POST /form] recebe a entrada do usuário. A anotação [@ModelAttribute], aplicada a um parâmetro, instrui o binding do modelo a criar o objeto a partir dos parâmetros da requisição (este é o comportamento padrão para um parâmetro de tipo classe; veja o Exemplo 08) e a armazená-lo no modelo da view. Sem um nome explícito, o nome do atributo é o da classe, com a primeira letra minúscula: [input]. O formulário é exibido novamente com os valores recebidos;
  • linhas 52 a 56: [getParameterMap()] também dá acesso aos parâmetros como foram enviados: um dicionário em que cada valor é um array de strings (um parâmetro pode se repetir). Ele é convertido em texto, uma linha por parâmetro, armazenado no modelo com o nome [received]. [Collectors.joining("\n")] concatena as linhas, separadas por uma quebra de linha.

O template [templates/layout.html] é o do Exemplo 17 (só o título muda). O arquivo [templates/form/form.html]:

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main>
  <h1 class="h3">A complete form</h1>
  <!--/* th:object: o objeto do formulário; *{...} designa um campo deste objeto */-->
  <form method="post" action="/form" th:object="${input}" style="max-width: 40rem">
    <!--/* campo oculto: enviado com o formulário, mas invisível */-->
    <input type="hidden" th:field="*{token}">

    <div class="mb-2">
      <span class="form-label me-3">Title</span>
      <!--/* botões de opção: mesmo [name], um único valor enviado */-->
      <div class="form-check form-check-inline" th:each="title : ${lists.titles}">
        <input class="form-check-input" type="radio" th:field="*{title}" th:value="${title}">
        <!--/* #ids.prev: o id atribuído por th:field ao campo anterior */-->
        <label class="form-check-label" th:for="${#ids.prev('title')}" th:text="${title}">Mr</label>
      </div>
    </div>

    <div class="row g-2 mb-2">
      <div class="col">
        <label class="form-label" for="name">Name</label>
        <!--/* th:field constrói os atributos id, name e value */-->
        <input class="form-control" type="text" th:field="*{name}">
      </div>
      <div class="col">
        <label class="form-label" for="password">Password</label>
        <!--/* uma senha NUNCA é enviada de volta na página: sem th:field */-->
        <input class="form-control" type="password" id="password" name="password">
      </div>
      <div class="col">
        <label class="form-label" for="birthDate">Date of birth</label>
        <!--/* um campo de data troca seus valores no formato yyyy-mm-dd */-->
        <input class="form-control" type="date" th:field="*{birthDate}">
      </div>
    </div>

    <div class="mb-2">
      <span class="form-label me-3">Hobbies</span>
      <!--/* caixas de seleção: mesmo [name], vários valores possíveis */-->
      <div class="form-check form-check-inline" th:each="hobby : ${lists.hobbies}">
        <input class="form-check-input" type="checkbox" th:field="*{hobbies}" th:value="${hobby}">
        <label class="form-check-label" th:for="${#ids.prev('hobbies')}" th:text="${hobby}">reading</label>
      </div>
    </div>

    <div class="row g-2 mb-2">
      <div class="col">
        <label class="form-label" for="country">Country</label>
        <select class="form-select" th:field="*{country}">
          <option th:each="c : ${lists.countries}" th:value="${c.code}" th:text="${c.name}">France</option>
        </select>
      </div>
      <div class="col">
        <label class="form-label" for="languages">Spoken languages</label>
        <!--/* lista de seleção múltipla: vários valores possíveis */-->
        <select class="form-select" th:field="*{languages}" multiple size="4">
          <option th:each="language : ${lists.languages}" th:value="${language}" th:text="${language}">French</option>
        </select>
      </div>
    </div>

    <div class="mb-2">
      <label class="form-label" for="comment">Comment</label>
      <!--/* uma área de texto: o valor fica ENTRE as tags */-->
      <textarea class="form-control" th:field="*{comment}" rows="2"></textarea>
    </div>

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

  <th:block th:if="${received != null}">
    <h2 class="h5 mt-3">What the server received</h2>
    <pre class="bg-light p-2 border" th:text="${received}">name = [...]</pre>
  </th:block>
</main>
</body>
</html>

Vamos detalhar este código:

  • Linha 7: o atributo [th:object] especifica o objeto do formulário: o atributo [input] do template. Dentro da tag, uma expressão de seleção [*{name}] refere-se à propriedade [name] desse objeto: é equivalente a [${input.name}];
  • Linha 9: o atributo [th:field="*{token}"] vincula o campo à propriedade [token]: ele escreve os atributos [id] e [name] (o nome da propriedade) e o atributo [value] (seu valor). Um campo oculto é enviado com o formulário, mas não é exibido. Ele serve para passar informações de uma página para a seguinte (no estudo de caso, por exemplo, contém a versão de um registro). Atenção: o usuário pode modificá-lo;
  • Linhas 14 a 18: os botões de opção compartilham o mesmo [name]; apenas um pode ser selecionado, e apenas um valor é enviado. Para um botão de opção, [th:field] não escreve o valor da propriedade em [value] ([th:value] é quem fornece o valor do botão): ele seleciona o botão se seu valor corresponder à propriedade. Como todos os botões têm o mesmo nome, [th:field] atribui a eles valores de [id] numerados: [title1], [title2]... O objeto utilitário [#ids.prev('title')] (linha 17) define o valor do último campo [title] como o [id] informado, para o atributo [for] de seu rótulo;
  • linha 25: um campo de texto: o [th:field] escreve [id="name"], [name="name"] e o valor. O rótulo da linha 23 pode, portanto, fixar [for="name"];
  • linha 30: uma senha nunca é devolvida em uma página: o campo não usa [th:field] e não tem um atributo [value];
  • linha 35: um campo de data. O navegador exibe a data em seu próprio formato, mas sempre envia e recebe [yyyy-mm-dd]; o [th:field] escreve a data nesse formato, graças à anotação [@DateTimeFormat];
  • linhas 42 a 45: caixas de seleção com o mesmo [name]: cada caixa marcada envia seu valor, de modo que o parâmetro se repete. O [th:field] marca a caixa se seu valor estiver na lista [hobbies];
  • linhas 51 a 53: uma lista suspensa. O [th:field] na tag [<select>] seleciona a opção cujo valor é igual à propriedade [country];
  • linhas 58 a 60: o atributo [multiple] permite selecionar várias opções: o [th:field] seleciona todas as opções que pertencem à lista [languages];
  • linha 67: o valor de uma caixa de texto fica dentro de suas tags, e não em um atributo [value]: o [th:field] sabe disso;
  • linhas 73 a 76: o que o servidor recebeu, exibido apenas após o envio, dentro de uma tag [<pre>], que preserva as quebras de linha.

Veja um trecho do código HTML gerado por esses atributos [th:field] (o campo oculto, o segundo botão de opção, as duas primeiras caixas de seleção, a lista suspensa):

    <input type="hidden" id="token" name="token" value="A7X2">
...
      <div class="form-check form-check-inline">
        <input class="form-check-input" type="radio" value="Mme" id="title2" name="title" checked="checked">

        <label class="form-check-label" for="title2">Mme</label>
      </div>
...
      <div class="form-check form-check-inline">
        <input class="form-check-input" type="checkbox" value="reading" id="hobbies1" name="hobbies"><input type="hidden" name="_hobbies" value="on"/>
        <label class="form-check-label" for="hobbies1">reading</label>
      </div>

      <div class="form-check form-check-inline">
        <input class="form-check-input" type="checkbox" value="music" id="hobbies2" name="hobbies"><input type="hidden" name="_hobbies" value="on"/>
        <label class="form-check-label" for="hobbies2">music</label>
      </div>
...
        <input type="hidden" name="_languages" value="1"/><select class="form-select" multiple size="4" id="languages" name="languages">
          <option value="French" selected="selected">French</option>

Observe os campos ocultos que nós não escrevemos: [_hobbies] depois de cada caixa de seleção, [_languages] antes da lista suspensa. Eles resolvem um problema do HTML: uma caixa desmarcada simplesmente não é enviada. Se o usuário desmarcar todas as caixas, o parâmetro [hobbies] não estará na requisição, e o binding do modelo não atualizaria a propriedade [hobbies], que manteria seu valor anterior. O [_hobbies] marcador, por outro lado, é sempre enviado: quando o [Spring] o encontra sem o parâmetro [hobbies], ele limpa a lista (ou define [false] para um valor booleano). Aqui, a entrada é um objeto novo cuja lista já está vazia, então a diferença não aparece; ela importa quando o objeto do formulário já foi preenchido anteriormente (por exemplo, armazenado em uma sessão; veja o capítulo “Escopos de dados”).

O formulário inicial (http://localhost:5000/form) e depois do envio:

Image

Image

Observe que:

  • A caixa de texto exibiu "[Hello <b>whole</b> world]" exatamente como foi digitado: "[th:field]" faz o escape do valor, e as tags digitadas não são interpretadas;
  • A senha foi recebida, mas não é exibida;
  • O navegador enviou os marcadores [_hobbies] (um por caixa de seleção) e [_languages].

Com o [curl], podemos ver a diferença quando uma caixa está marcada:

curl -d "token=A7X2&title=Mr&name=Martin&hobbies=sport" http://localhost:5000/form
1
2
3
4
    <pre class="bg-light p-2 border">token = [A7X2]
title = [Mr]
name = [Martin]
hobbies = [sport]</pre>

e duas caixas marcadas:

curl -d "token=A7X2&title=Mr&name=Martin&hobbies=sport&hobbies=music" http://localhost:5000/form
1
2
3
4
    <pre class="bg-light p-2 border">token = [A7X2]
title = [Mr]
name = [Martin]
hobbies = [sport, music]</pre>

(apenas a tag [<pre>] da página é reproduzida). A opção [-d] do [curl] envia uma requisição POST, com este corpo, e o cabeçalho [Content-Type: application/x-www-form-urlencoded] de um formulário HTML.

4.7. Exemplo 19: Validação de formulário

Um formulário inválido deve ser exibido novamente, mostrando os valores digitados e uma mensagem abaixo de cada campo com erro. O Exemplo 19 aplica a técnica do Exemplo 09 (validação feita pela ação, usando o parâmetro [BindingResult]) a um formulário de cadastro e demonstra como o [Thymeleaf] exibe os erros.

A validação requer uma dependência adicional. O arquivo [pom.xml]:

  <dependencies>
    <!-- as views Thymeleaf -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-thymeleaf</artifactId>
    </dependency>
    <!-- validação (Bean Validation, Hibernate Validator) -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
  </dependencies>
  • linhas 7 a 11: o starter de validação: a API [Bean Validation] (as anotações [@NotBlank], [@Size]...) e sua implementação, [Hibernate Validator] (veja o Exemplo 08).

O arquivo [models/RegistrationModel.java]:

package example19.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;

// os campos do formulário e suas restrições
public class RegistrationModel {

    @NotBlank(message = "The name is required.")
    @Size(max = 20, message = "The name must not exceed 20 characters.")
    private String name;

    @NotBlank(message = "The email address is required.")
    @Email(message = "Invalid email address.")
    private String email;

    // tudo o que vem de um formulário é uma string: "42" -> 42
    @NotNull(message = "The age is required.")
    @Min(value = 18, message = "The age must be between 18 and 120 years.")
    @Max(value = 120, message = "The age must be between 18 and 120 years.")
    private Integer age;

    @NotBlank(message = "The password is required.")
    @Size(min = 6, message = "The password must have at least 6 characters.")
    private String password;

    private String confirmation;

    // uma regra sobre DOIS campos: um método booleano, validado por
    // @AssertTrue. Para o Bean Validation, é a propriedade [confirmationValid].
    @AssertTrue(message = "The confirmation does not match the password.")
    public boolean isConfirmationValid() {
        return Objects.equals(password, confirmation);
    }

    public String getName() { return name; }
    public void setName(String name) { this.name = name; }

    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 getPassword() { return password; }
    public void setPassword(String password) { this.password = password; }

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

Vamos comentar este código:

  • linhas 16 a 18: o nome é obrigatório ([@NotBlank] rejeita [null], uma string vazia e uma string formada apenas por espaços) e limitado a 20 caracteres;
  • linhas 20 a 22: [@Email] valida o formato de um endereço de e-mail;
  • linhas 25 a 28: a idade é convertida em um inteiro e depois validada. O tipo [Integer] (e não [int]) admite o valor [null]: uma idade ausente permanece como [null], e [@NotNull] sinaliza isso;
  • linhas 30 a 32: pelo menos 6 caracteres. [@Size] não valida um valor [null]: esse é o papel de [@NotBlank];
  • linhas 38 a 41: a regra “a confirmação é igual à senha” envolve dois campos. O [Bean Validation] não tem uma anotação predefinida para isso; a solução mais simples é um método booleano que faz a comparação, anotado com [@AssertTrue]: a restrição é violada se o método retornar [false]. Para o [Bean Validation], um método chamado [isXxx()] serve como acessor de uma propriedade booleana: qualquer erro será, portanto, associado à propriedade [confirmationValid]. [Objects.equals] compara dois objetos, assim como [null].

O arquivo [controllers/RegistrationController.java]:

package example19.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 example19.models.RegistrationModel;
import jakarta.validation.Valid;

@Controller
@RequestMapping("/register")
public class RegistrationController {

    // @InitBinder: configura o binding de modelo das ações deste controller.
    // StringTrimmerEditor(true): de cada string recebida são removidos os
    // espaços supérfluos, e uma string vazia se torna null
    @InitBinder
    public void initBinder(WebDataBinder binder) {
        binder.registerCustomEditor(String.class, new StringTrimmerEditor(true));
    }

    // ?html5=true: deixamos o navegador validar o formulário antes do envio
    @GetMapping("")
    public String display(@RequestParam(defaultValue = "false") boolean html5, Model model) {
        model.addAttribute("registration", new RegistrationModel());
        model.addAttribute("html5", html5);
        return "registration/registration";
    }

    // @ModelAttribute("registration"): o nome do objeto no modelo da view
    @PostMapping("")
    public String register(@Valid @ModelAttribute("registration") RegistrationModel input, BindingResult result,
            @RequestParam(defaultValue = "false") boolean html5, Model model) {
        if (result.hasErrors()) {
            // exibimos o formulário NOVAMENTE: valores digitados (exceto as senhas),
            // e uma mensagem sob cada campo inválido (veja fragments/field.html)
            input.setPassword(null);
            input.setConfirmation(null);
            model.addAttribute("html5", html5);
            model.addAttribute("error", "The form contains errors.");
            return "registration/registration";
        }
        return "registration/welcome";
    }
}

Vamos detalhar este código:

  • Linhas 25 a 28: um método anotado com [@InitBinder] configura o binding do modelo para as ações deste controller. Ele recebe o objeto [WebDataBinder], que realiza o binding. Um editor de propriedade é registrado ali para o tipo [String]: [StringTrimmerEditor] remove os espaços no início e no fim de cada string recebida; com o argumento [true], uma string vazia se torna [null]. Um nome digitado como [" Martin "] se torna ["Martin"]. Atenção: isso se aplica a todas as strings, inclusive às senhas;
  • linhas 31 a 36: o formulário vazio. O parâmetro [html5] será explicado mais adiante. O objeto do formulário é armazenado no template com o nome [registration];
  • linha 40: [@Valid] solicita a validação do objeto; [@ModelAttribute("registration")] o armazena no modelo com o nome [registration], o mesmo da linha 33, que é o usado pela view. O parâmetro [BindingResult] deve seguir imediatamente o objeto validado: ele recebe os erros de binding e de validação, e a ação é então sempre executada (veja o Exemplo 09);
  • linha 41: [@RequestParam] lê um parâmetro da URL ou do corpo da requisição: aqui, [html5] vem da URL do formulário;
  • linhas 42 a 50: se houver erros, o formulário é exibido novamente com os valores digitados (exceto as senhas) e uma mensagem geral armazenada no template. Não há mais nada a fazer: o objeto [registration] e seus erros ([BindingResult]) já estão no modelo, onde a view os encontrará;
  • linha 51: caso contrário, a página de boas-vindas, que também usa o objeto [registration] do modelo.

Um erro de conversão (uma idade [abc]) gera uma mensagem padrão em inglês difícil de ler: [Failed to convert property value of type java.lang.String to required type java.lang.Integer for property age; For input string: "abc"]. O arquivo [messages.properties] a substitui:

1
2
3
# as mensagens dos erros de CONVERSÃO (p. ex., idade "abc"), técnicas por padrão;
# a chave: typeMismatch.<tipo Java esperado>
typeMismatch.java.lang.Integer=The value entered is not an integer.
  • Linha 3: o [Spring Boot] lê automaticamente o arquivo de recursos [messages.properties]: é o arquivo de mensagens da aplicação (o próximo capítulo explicará como ele é localizado em vários idiomas). Em caso de erro de conversão, o [Spring] procura uma mensagem em várias chaves, da mais específica à mais geral: [typeMismatch.registration.age] (o objeto e sua propriedade), [typeMismatch.age] (a propriedade), [typeMismatch.java.lang.Integer] (o tipo esperado) e, por fim, [typeMismatch]. A primeira encontrada tem precedência; caso contrário, usa-se a mensagem em inglês. Em um arquivo como esse, o apóstrofo deve ser escrito duas vezes (em francês, por exemplo: [n''est]): as mensagens são processadas pela classe [MessageFormat] do [Java], para a qual o apóstrofo simples é um caractere especial. O estudo de caso substitui, assim, todas essas mensagens.

4.7.1. Um fragmento de campo

Todos os campos seguem o mesmo padrão: um rótulo, um campo e uma mensagem de erro. Um fragmento extrai esses componentes. O arquivo [templates/fragments/field.html]:

<!--/* um campo de entrada, com seu rótulo e sua mensagem de erro. O fragmento tem
       tem assinatura: seus parâmetros são variáveis nomeadas e opcionais:
       name, label, type e as restrições HTML5 required, maxlength, minlength,
       min, max. [errorOf]: a propriedade cujo erro é exibido (name por padrão) */-->
<div class="mb-2" th:fragment="field" th:with="key=${errorOf ?: name}">
  <label class="form-label" th:for="${name}" th:text="${label}">Label</label>
  <!--/* __${name}__: PRÉ-PROCESSAMENTO; ${name} é avaliado primeiro, e seu resultado
         ("email") substitui a expressão: th:field="*{email}" */-->
  <input class="form-control" th:type="${type}" th:field="*{__${name}__}"
         th:classappend="${#fields.hasErrors(key)} ? 'is-invalid'"
         th:required="${required}"
         th:attr="maxlength=${maxlength},minlength=${minlength},min=${min},max=${max}">
  <!--/* a PRIMEIRA mensagem de erro do campo, abaixo do campo */-->
  <div class="invalid-feedback" th:if="${#fields.hasErrors(key)}" th:text="${#fields.errors(key)[0]}">error</div>
</div>

Vamos comentar este código:

  • Linha 5: o fragmento [field] é declarado sem assinatura, isto é, sem lista de parâmetros. Ele será chamado com parâmetros nomeados ([field(name='age', label='Age', ...)]), que se tornam variáveis do fragmento; um parâmetro não fornecido simplesmente é definido como [null]. Isso é útil para um fragmento com muitos parâmetros opcionais. [th:with] declara a variável [key]: o nome da propriedade para a qual o erro é exibido. O operador [?:] (conhecido como “Elvis”) retorna seu operando da esquerda se ele não for [null]e, caso contrário, seu operando da direita: [errorOf] se fornecido, [name] caso contrário;
  • Linha 9: [th:type] escreve o atributo [type]. [th:field] deve receber o nome da propriedade, que está armazenado na variável [name]. Não é possível escrever [*{name}] (isso seria a propriedade [name]): use a etapa de pré-processamento [__...__]. A expressão entre os sublinhados duplos é avaliada primeiro, e seu resultado substitui o texto: se [name] for igual a [email], o atributo se torna [th:field="*{email}"], que é então avaliado normalmente. O [th:field] usa o objeto do formulário ([th:object]), declarado pela view que insere o fragmento;
  • linha 10: [#fields.hasErrors(key)] indica se a propriedade tem erros no [BindingResult] do objeto do formulário. As classes [Bootstrap] e [is-invalid] destacam então o campo em vermelho;
  • linha 11: o atributo booleano [required] é escrito se [required] for verdadeiro; caso contrário, é omitido;
  • linha 12: [th:attr] escreve vários atributos de uma só vez. Um atributo com valor [null] não é escrito: cada campo recebe apenas as restrições HTML5 que se aplicam a ele;
  • linha 14: a mensagem de erro, abaixo do campo (classe [Bootstrap] [invalid-feedback]). [#fields.errors(key)] retorna a lista de mensagens da propriedade; uma propriedade pode violar várias restrições, e apenas a primeira é exibida ([[0]]).

O arquivo [templates/registration/registration.html]:

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main>
  <h1 class="h3">Registration</h1>
  <p th:if="${html5}">Browser validation <b>enabled</b> - <a href="/register">disable it</a></p>
  <p th:unless="${html5}">Browser validation <b>disabled</b> - <a href="/register?html5=true">enable it</a></p>
  <!--/* novalidate: o navegador ignora os atributos required, min... e
         envia o formulário como está; somente o servidor valida */-->
  <form method="post" th:action="${html5} ? '/register?html5=true' : '/register'"
        th:novalidate="${!html5}" th:object="${registration}">
    <div th:replace="~{fragments/field :: field(name='name', label='Name', type='text', required=true, maxlength=20)}"></div>
    <div th:replace="~{fragments/field :: field(name='email', label='Email address', type='email', required=true)}"></div>
    <div th:replace="~{fragments/field :: field(name='age', label='Age', type='number', required=true, min=18, max=120)}"></div>
    <div th:replace="~{fragments/field :: field(name='password', label='Password', type='password', required=true, minlength=6)}"></div>
    <div th:replace="~{fragments/field :: field(name='confirmation', label='Confirmation', type='password', required=true, errorOf='confirmationValid')}"></div>
    <button class="btn btn-primary" type="submit">Register</button>
  </form>
</main>
</body>
</html>
  • linhas 6 e 7: o link que ativa ou desativa a validação pelo navegador;
  • linha 10: o atributo [action] do formulário armazena o parâmetro [html5];
  • linha 11: o atributo booleano [novalidate] é definido quando [html5] é falso. [th:object] refere-se ao objeto do formulário, [registration];
  • Linhas 12 a 16: cada campo é uma inserção do fragmento, com parâmetros nomeados. Para a confirmação (linha 16), o erro a exibir é o da propriedade [confirmationValid], e o da regra [@AssertTrue].

O arquivo [templates/layout.html]:

<!doctype html>
<html lang="en" xmlns:th="http://www.thymeleaf.org" th:fragment="page(content)">
<head>
  <meta charset="utf-8">
  <title>Registration</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="${content}"></main>
    <!--/* o erro global, no pé da página, sobre um fundo rosa claro; [error] é definido pela ação */-->
    <div class="error-area" role="alert" th:if="${error != null}" th:text="${error}">error</div>
  </div>
</body>
</html>
  • Linha 13: a mensagem global é exibida na parte inferior da página, sobre um fundo rosa claro (classe [error-area] derivada de [static/css/styles.css]), como mostrado no estudo de caso.

O arquivo [templates/registration/welcome.html]:

1
2
3
4
5
6
7
8
9
<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main th:object="${registration}">
  <h1 class="h3" th:text="|Welcome *{name}|">Welcome</h1>
  <p>Your registration is saved: address <b th:text="*{email}">email</b>, age <b th:text="*{age}">42</b> years.</p>
</main>
</body>
</html>
  • Linha 4: [th:object] não é reservado para formulários: na tag [<main>], ele permite escrever [*{name}] em vez de [${registration.name}];
  • Linhas 5 e 6: os valores convertidos e limpos: a idade é um número, e o nome não contém mais espaços.

O formulário vazio (http://localhost:5000/register) e, em seguida, enviado com vários erros (um nome formado por espaços, um endereço incompleto, uma idade muito baixa e senhas curtas demais e diferentes):

Image

Image

depois preenchido corretamente (com espaços em volta do nome):

Image

E com uma idade não numérica, enviada pelo [curl] (o navegador a teria rejeitado em um campo [type="number"]):

curl -i -d "name=Martin&email=xx&age=abc" http://localhost:5000/register
HTTP/1.1 200
Content-Type: text/html;charset=UTF-8

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Registration</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">Registration</h1>

  <p>Browser validation <b>disabled</b> - <a href="/register?html5=true">enable it</a></p>

  <form method="post" action="/register" novalidate="novalidate">
    <div class="mb-2">
  <label class="form-label" for="name">Name</label>

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


</div>
    <div class="mb-2">
  <label class="form-label" for="email">Email address</label>

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

  <div class="invalid-feedback">Invalid email address.</div>
</div>
    <div class="mb-2">
  <label class="form-label" for="age">Age</label>

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

  <div class="invalid-feedback">The value entered is not an integer.</div>
</div>
    <div class="mb-2">
  <label class="form-label" for="password">Password</label>

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

  <div class="invalid-feedback">The password is required.</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">Register</button>
  </form>
</main>

    <div class="error-area" role="alert">The form contains errors.</div>
  </div>
</body>
</html>

Observe que:

  • o erro de conversão da idade usa a mensagem de [messages.properties];
  • o campo [age] não exibe novamente o valor rejeitado [abc]: em um campo [type="number"], o [th:field] não escreve um valor que não seja um número (com [type="text"], ele teria escrito [value="abc"]);
  • a senha ausente tem apenas um erro, “obrigatório”: [@Size] não valida um valor [null]. A confirmação, porém, não tem erros: duas senhas ausentes são iguais;
  • os campos sem erros não têm a classe [is-invalid], e seu fragmento não gera mensagem.

4.7.2. Validação pelo navegador

Os atributos [required], [maxlength], [min], [max], [type="email"]... instruem o navegador a validar o formulário antes de enviá-lo: o usuário é avisado imediatamente por meio de uma dica de tela, sem nenhuma comunicação de ida e volta com o servidor. Esse é o comportamento obtido ao clicar no link “enable it” (http://localhost:5000/register?html5=true), que remove o atributo [novalidate] do formulário.

Essa validação é uma conveniência, não uma medida de segurança: ela pode ser contornada simplesmente removendo o atributo [required] com as ferramentas de desenvolvedor do navegador ou enviando a requisição com o [curl]. A validação no servidor continua essencial. É por isso que o exemplo desativa a validação do navegador por padrão: para demonstrar o funcionamento do servidor. O estudo de caso, porém, mantém as duas: os atributos HTML5 por conveniência e a validação no servidor por segurança.

4.8. Exemplo 20: O padrão Post/Redirect/Get

Quando um formulário POST é enviado com sucesso, a ação pode exibir uma página diretamente. O problema surge se o usuário recarregar essa página (tecla F5): o navegador reenvia o formulário, e a operação é executada uma segunda vez (um pedido feito duas vezes, uma consulta marcada duas vezes...). O padrão Post / Redirect / Get (PRG) evita esse problema: uma ação POST bem-sucedida não gera uma página; em vez disso, ela redireciona para uma página GET. Recarregar essa página apenas dispara outro GET, sem nenhum efeito.

Resta um detalhe: a página GET deve exibir uma mensagem (“a tarefa foi adicionada”), embora essa mensagem tenha sido gerada pela ação POST em outra requisição. O [Spring MVC] fornece para isso os atributos flash: atributos definidos antes do redirecionamento, que persistem até a próxima requisição, onde são adicionados ao template e depois desaparecem. Isso é conhecido como mensagem flash. Por padrão, o [Spring MVC] armazena os atributos flash na sessão HTTP do usuário: um espaço de memória que o servidor associa a cada navegador (o capítulo “Escopos de dados” é dedicado a esse tema).

O arquivo [services/TasksService.java]:

package example20.services;

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

import org.springframework.stereotype.Service;

// a lista de tarefas, em memória, compartilhada por todos (singleton).
// CopyOnWriteArrayList: uma lista utilizável por várias requisições simultâneas
@Service
public class TasksService {

    private final List<String> tasks = new CopyOnWriteArrayList<>(List.of("Read chapter 3"));

    public List<String> list() {
        return List.copyOf(tasks);
    }

    public void add(String label) {
        tasks.add(label);
    }
}
  • linha 13: um singleton é compartilhado por todas as requisições, que podem ser executadas simultaneamente. Um [ArrayList] comum não suporta isso; [CopyOnWriteArrayList] é uma lista projetada para essa finalidade;
  • Linhas 15 a 17: [List.copyOf] retorna uma cópia somente leitura da lista: quem chama não pode modificar a lista do serviço.

O arquivo [controllers/TasksController.java]:

package example20.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 example20.services.TasksService;

@Controller
@RequestMapping("/tasks")
public class TasksController {

    private final TasksService tasks;

    public TasksController(TasksService tasks) {
        this.tasks = tasks;
    }

    // GET /tasks: a lista e o formulário de adição
    @GetMapping("")
    public String display(Model model) {
        model.addAttribute("tasks", tasks.list());
        return "tasks/tasks";
    }

    // POST /tasks: o padrão Post / Redirect / Get
    @PostMapping("")
    public String add(@RequestParam(required = false) String label, Model model,
            RedirectAttributes redirect) {
        String text = label == null ? "" : label.trim();
        if (text.isEmpty() || text.length() > 40) {
            // entrada inválida: exibimos a página novamente, sem redirecionamento
            model.addAttribute("label", label);
            model.addAttribute("error", "The label must have 1 to 40 characters.");
            return display(model);
        }
        tasks.add(text);
        // um atributo "flash": ele sobreviverá ao redirecionamento, para a PRÓXIMA requisição
        redirect.addFlashAttribute("flash", "The task [" + text + "] has been added.");
        // sem página: um redirecionamento para a página GET
        return "redirect:/tasks";
    }

    // POST /tasks/without-prg: o contraexemplo (uma página em resposta ao POST)
    @PostMapping("/without-prg")
    public String addWithoutPrg(@RequestParam(required = false) String label, Model model) {
        tasks.add(label == null || label.isBlank() ? "(untitled)" : label.trim());
        model.addAttribute("withoutPrg", true);
        return display(model);
    }
}

Vamos comentar este código:

  • linhas 24 a 28: a página de listagem;
  • linha 33: um parâmetro do tipo [RedirectAttributes], fornecido pelo [Spring MVC]: os atributos de redirecionamento;
  • linhas 35 a 40: uma entrada inválida: a página é exibida novamente sem redirecionamento (a entrada e a mensagem de erro precisam ser mantidas). A linha 39 simplesmente chama o método [display], como qualquer método [Java]: ele adiciona a lista de tarefas ao template e retorna o nome da view;
  • Linha 43: uma entrada válida: depois da operação, [addFlashAttribute] define a mensagem flash a exibir;
  • linha 45: uma string iniciada por [redirect:] não é um nome de view: [Spring MVC] responde com um redirecionamento (código 302) para o endereço seguinte (veja o exemplo 04);
  • linhas 49 a 54: o contraexemplo, para comparação: uma página como resposta a um POST.

O arquivo [templates/tasks/tasks.html]:

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main>
  <h1 class="h3">My tasks</h1>
  <ol>
    <li th:each="task : ${tasks}" th:text="${task}">task</li>
  </ol>
  <form method="post" action="/tasks" class="d-flex gap-2">
    <input class="form-control" name="label" th:value="${label}" placeholder="New task">
    <button class="btn btn-primary text-nowrap" type="submit">Add</button>
    <!--/* formaction: este botão envia o MESMO formulário para outro endereço */-->
    <button class="btn btn-outline-secondary text-nowrap" type="submit" formaction="/tasks/without-prg">Add without PRG</button>
  </form>
  <p class="text-danger mt-2" th:if="${withoutPrg}">Page displayed in response to a POST: press F5 and the task will be added a second time.</p>
</main>
</body>
</html>
  • linha 10: a entrada, exibida novamente após um erro (o atributo [label] não existe nos outros casos: o campo fica vazio);
  • linha 13: o atributo [formaction] de um botão envia o formulário para um endereço diferente do atributo [action] do formulário. O formulário tem, assim, dois botões, que disparam duas ações diferentes. O estudo de caso usa essa abordagem em sua página de login;
  • linha 15: um atributo ausente do template é definido como [null], e [th:if] trata [null] como falso.

O arquivo [templates/layout.html]:

<!doctype html>
<html lang="en" xmlns:th="http://www.thymeleaf.org" th:fragment="page(content)">
<head>
  <meta charset="utf-8">
  <title>Tasks</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">
    <!--/* a mensagem flash, no topo da página: um atributo de modelo, definido ANTES do redirecionamento */-->
    <div class="alert alert-success" role="status" th:if="${flash != null}" th:text="${flash}">flash</div>
    <main th:replace="${content}"></main>
    <div class="error-area" role="alert" th:if="${error != null}" th:text="${error}">error</div>
  </div>
</body>
</html>

A mensagem flash é exibida no topo da página (linha 12), e o erro na parte inferior (linha 14). Do ponto de vista da view, um atributo flash é apenas mais um atributo do modelo.

Veja o que o [curl] enxerga quando o formulário é enviado com sucesso. A opção [-c file] salva os cookies recebidos, [-b file] os envia de volta; [--data-urlencode] codifica os espaços e os acentos no campo:

curl -i -c cookies.txt -b cookies.txt --data-urlencode "label=Review Spring" http://localhost:5000/tasks
1
2
3
4
HTTP/1.1 302
Set-Cookie: JSESSIONID=74250348252FFBFF6F46F1BDFDDF7DEA; Path=/; HttpOnly
Location: http://localhost:5000/tasks
Content-Length: 0

A resposta é um redirecionamento para [/tasks]. Para armazenar a mensagem flash, o [Spring MVC] criou uma sessão HTTP: o servidor ([Tomcat]) atribuiu a ela um identificador, que foi enviado ao navegador no cookie [JSESSIONID]. A requisição seguinte devolve esse cookie, permitindo que o servidor recupere a sessão e a mensagem:

curl -i -c cookies.txt -b cookies.txt http://localhost:5000/tasks
HTTP/1.1 200
Content-Type: text/html;charset=UTF-8

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Tasks</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">The task [Review Spring] has been added.</div>
    <main>
  <h1 class="h3">My tasks</h1>
  <ol>
    <li>Read chapter 3</li>
    <li>Review Spring</li>
  </ol>
  <form method="post" action="/tasks" class="d-flex gap-2">
    <input class="form-control" name="label" value="" placeholder="New task">
    <button class="btn btn-primary text-nowrap" type="submit">Add</button>

    <button class="btn btn-outline-secondary text-nowrap" type="submit" formaction="/tasks/without-prg">Add without PRG</button>
  </form>

</main>

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

A mensagem flash é exibida; se a página for recarregada, ela desaparece. A sessão, porém, continua aberta: seu identificador não muda, e o servidor não reenvia o cookie.

O arquivo [application.properties] contém uma configuração relacionada à sessão:

1
2
3
4
5
6
7
# a porta de escuta do servidor (8080 por padrão)
server.port=5000
# as respostas de erro do Spring Boot não contêm a pilha de chamadas
spring.web.error.include-stacktrace=never
# a sessão (que carrega os atributos flash) é rastreada por um cookie
# apenas, nunca por um ";jsessionid=..." adicionado às URLs
server.servlet.session.tracking-modes=cookie
  • Linha 7: a sessão é rastreada apenas por um cookie. Sem essa configuração, o [Tomcat] não sabe, durante a primeira resposta, se o navegador aceita cookies: ele envia o cookie, mas também acrescenta o identificador da sessão à URL do redirecionamento. O resultado é:
1
2
3
4
HTTP/1.1 302
Set-Cookie: JSESSIONID=836C471F9879CC83E0C2C4C1ED8FD048; Path=/; HttpOnly
Location: http://localhost:5000/tasks;jsessionid=836C471F9879CC83E0C2C4C1ED8FD048
Content-Length: 0

A URL e [/tasks;jsessionid=...] funcionam, mas aparecem na barra de endereços do navegador, e um identificador de sessão circulando na URL (histórico de navegação, favoritos, links copiados) representa um risco de segurança. Todos os exemplos que usam atributos flash têm essa configuração.

No navegador (http://localhost:5000/tasks), depois de adicionar uma tarefa:

Image

A barra de endereços exibe [/tasks]: é a página GET. Você pode recarregá-la sem receio; a mensagem desaparece. Uma entrada contendo espaços:

Image

E o contraexemplo:

Image

Aqui, a barra de endereços exibe [/tasks/without-prg], o endereço do POST. Recarregar a página dispara um aviso do navegador (“Confirm form submission”) e, em seguida, adiciona a tarefa uma segunda vez. Todos os formulários POST do estudo de caso seguem o esquema PRG. No entanto, o estudo de caso armazena seus atributos flash em um cookie, e não na sessão, porque seu servidor não retém nenhum dado entre as requisições.

Uma regra simples orienta a escolha entre um link e um botão:

  • um link ([<a href>]) gera uma requisição (GET). Uma requisição (GET) não deve modificar nada: navegadores, mecanismos de busca e antivírus podem seguir links por conta própria para preparar uma página ou analisá-la;
  • uma operação que modifica dados (adicionar, editar, excluir, sair) é um botão em um formulário POST.

O Exemplo 21 gerencia uma lista de contatos: você visualiza um contato por meio de um link e o exclui por meio de um botão, que abre uma janela de confirmação. Os arquivos deste exemplo:

21-links-buttons/
├── src/
│   └── main/
│       ├── java/
│       │   └── example21/
│       │       ├── config/
│       │       │   └── WebConfig.java
│       │       ├── controllers/
│       │       │   └── ContactsController.java
│       │       ├── services/
│       │       │   └── ContactsService.java
│       │       └── Example21Application.java
│       └── resources/
│           ├── static/
│           │   ├── css/
│           │   │   └── styles.css
│           │   └── js/
│           │       └── app.js
│           ├── templates/
│           │   ├── contacts/
│           │   │   ├── details.html
│           │   │   └── list.html
│           │   ├── fragments/
│           │   │   └── confirmation.html
│           │   └── layout.html
│           └── application.properties
└── pom.xml

O arquivo [services/ContactsService.java]:

package example21.services;

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

import org.springframework.stereotype.Service;

// os contatos, em memória, compartilhados por todos (singleton)
@Service
public class ContactsService {

    // um contato: um identificador, um nome, um número de telefone
    public record Contact(int id, String name, String phone) {
    }

    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 lastId = 3;

    // synchronized: uma única requisição por vez executa o método
    public synchronized List<Contact> list() {
        return List.copyOf(contacts);
    }

    // Optional: um contato, ou "nada" se ele não existir
    public synchronized Optional<Contact> read(int id) {
        return contacts.stream().filter(c -> c.id() == id).findFirst();
    }

    public synchronized Optional<Contact> edit(int id, String name, String phone) {
        for (int i = 0; i < contacts.size(); i++) {
            if (contacts.get(i).id() == id) {
                // um record é imutável: nós o substituímos por um novo
                Contact edited = new Contact(id, name, phone);
                contacts.set(i, edited);
                return Optional.of(edited);
            }
        }
        return Optional.empty();
    }

    public synchronized Contact add(String name, String phone) {
        Contact contact = new Contact(++lastId, name, phone);
        contacts.add(contact);
        return contact;
    }

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

Vamos comentar este código:

  • linhas 14 e 15: um contato;
  • linhas 17 a 20: a lista de contatos: um [ArrayList] (editável), inicializado com três contatos;
  • linha 24: a palavra-chave [synchronized] garante que apenas uma requisição por vez execute um método [synchronized] do objeto: requisições simultâneas não podem modificar a lista ao mesmo tempo. É uma solução diferente da lista [CopyOnWriteArrayList] do Exemplo 20;
  • linhas 29 a 31: [read] retorna um [Optional<Contact>] (veja o Exemplo 06): um objeto que contém um contato ou nada, se nenhum contato tiver esse ID. [findFirst()] retorna o primeiro elemento do stream como um [Optional];
  • linhas 36 a 38: um record é imutável: seus campos não são modificados; em vez disso, ele é substituído por um novo;
  • linha 46: [++lastId] incrementa o contador antes de usá-lo: os identificadores seguintes são 4, 5...;
  • linha 53: [ifPresent] executa uma ação se o [Optional] contiver um contato. [contacts::remove] é uma referência de método: uma forma abreviada de escrever a lambda [c -> contacts.remove(c)].

O arquivo [controllers/ContactsController.java]:

package example21.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 example21.services.ContactsService;
import example21.services.ContactsService.Contact;

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

    private final ContactsService contacts;

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

    // um LINK (<a href>): uma requisição GET, que não modifica nada
    @GetMapping("")
    public String list(Model model) {
        model.addAttribute("contacts", contacts.list());
        return "contacts/list";
    }

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

    // um BOTÃO em um formulário POST: uma requisição que modifica dados
    @PostMapping("/{id:\\d+}")
    public String save(@PathVariable int id, @RequestParam String name, @RequestParam String phone,
            RedirectAttributes redirect) {
        Contact contact = contacts.edit(id, name, phone).orElseThrow(ContactsController::notFound);
        redirect.addFlashAttribute("flash", "The contact [" + contact.name() + "] has been edited.");
        return "redirect:/contacts";
    }

    // mesmo formulário, outro botão (atributo formaction): outra ação
    @PostMapping("/{id:\\d+}/duplicate")
    public String duplicate(@PathVariable int id, @RequestParam String name, @RequestParam String phone,
            RedirectAttributes redirect) {
        Contact copy = contacts.add(name + " (copy)", phone);
        redirect.addFlashAttribute("flash", "The contact [" + copy.name() + "] has been created.");
        return "redirect:/contacts";
    }

    @PostMapping("/{id:\\d+}/delete")
    public String delete(@PathVariable int id, RedirectAttributes redirect) {
        Contact contact = contacts.delete(id).orElseThrow(ContactsController::notFound);
        redirect.addFlashAttribute("flash", "The contact [" + contact.name() + "] has been deleted.");
        return "redirect:/contacts";
    }

    // uma exceção que produz uma resposta 404
    private static ResponseStatusException notFound() {
        return new ResponseStatusException(HttpStatus.NOT_FOUND, "unknown contact");
    }
}

Vamos comentar este código:

  • linhas 28 a 38: as duas páginas, a lista e o perfil do contato. A restrição [{id:\\d+}] (veja o Exemplo 02) aceita apenas um identificador formado por dígitos;
  • linha 36: [orElseThrow] retorna o contato contido no [Optional] ou, se ele estiver vazio, lança a exceção gerada pela função que lhe é passada: aqui, a referência de método [ContactsController::notFound];
  • linhas 41 a 47: gravação de um registro em PRG. Os parâmetros [name] e [phone] são obrigatórios: [@RequestParam] não pode ser usado sem [required = false];
  • linhas 50 a 56: duplicação, disparada por um segundo botão no mesmo formulário (atributo [formaction]);
  • linhas 58 a 63: exclusão, por meio de um POST;
  • linhas 66 a 68: uma exceção [ResponseStatusException] carrega um código HTTP e um motivo. Disparada por uma ação, ela gera uma resposta de erro com esse código: neste caso, 404. Um contato inexistente dispara, assim, um 404 nas ações [details], [save] e [delete]; a duplicação, por outro lado, não relê o contato: ela cria uma cópia com base nos campos recebidos.

O arquivo [templates/contacts/list.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.name}">Marie Durand</td>
        <td th:text="${contact.phone}">01 23 45 67 89</td>
        <td class="text-end">
          <!--/* view: um link simples; @{/contacts/{id}(id=...)}: uma URL com uma variável */-->
          <a class="btn btn-sm btn-outline-primary" th:href="@{/contacts/{id}(id=${contact.id})}">View</a>
          <!--/* delete: um formulário POST, cujo envio será confirmado */-->
          <form method="post" class="d-inline" th:action="@{/contacts/{id}/delete(id=${contact.id})}"
                th:data-confirmation="|Delete the contact ${contact.name}?|">
            <button class="btn btn-sm btn-outline-danger" type="submit">Delete</button>
          </form>
        </td>
      </tr>
    </tbody>
  </table>
</main>
</body>
</html>
  • Linha 13: View: um link, exibido como botão pelo [Bootstrap]. A expressão de link [@{/contacts/{id}(id=${contact.id})}] contém uma variável de caminho [{id}], preenchida pelo parâmetro de mesmo nome entre parênteses: [/contacts/1]. Um parâmetro que não corresponde a nenhuma variável de caminho é adicionado depois de [?] (veja o Exemplo 16);
  • linhas 15 e 16: excluir: um pequeno formulário POST, reduzido ao seu botão. O atributo [data-confirmation] contém a pergunta a ser feita antes do envio. Os atributos [data-*] são livres: o HTML os ignora, enquanto o [JavaScript] da página pode lê-los. O [Thymeleaf] pode escrever qualquer atributo: [th:data-confirmation] calcula o atributo [data-confirmation], cujo valor passa por escape.

O arquivo [templates/contacts/details.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 no. *{id}|">Contact no. 1</h1>
  <form method="post" th:action="@{/contacts/{id}(id=*{id})}">
    <div class="mb-2">
      <label class="form-label" for="name">Name</label>
      <input class="form-control" id="name" name="name" th:value="*{name}">
    </div>
    <div class="mb-3">
      <label class="form-label" for="phone">Phone</label>
      <input class="form-control" id="phone" name="phone" th:value="*{phone}">
    </div>
    <!--/* dois botões de envio para o mesmo formulário */-->
    <button class="btn btn-primary" type="submit">Save</button>
    <button class="btn btn-outline-primary" type="submit" th:formaction="@{/contacts/{id}/duplicate(id=*{id})}">Duplicate</button>
    <a class="btn btn-link" href="/contacts">Back to the list</a>
  </form>
</main>
</body>
</html>
  • linha 4: [th:object] na tag [<main>]: o contato é o objeto selecionado, e [*{id}] refere-se ao seu ID;
  • linha 6: o endereço do formulário, com uma variável de caminho preenchida por uma expressão de seleção;
  • Linhas 9 e 13: este formulário não usa [th:field]: os campos não estão vinculados a um objeto de formulário, portanto [th:value] é suficiente;
  • linhas 16 e 17: dois botões de envio para o mesmo formulário; o segundo tem seu próprio atributo [formaction].

4.9.1. A janela de confirmação

A caixa de diálogo do navegador ([window.confirm]) não pode ser formatada nem traduzida: seus botões permanecem no idioma do navegador. Ela é substituída por uma janela do [Bootstrap], incorporada à página e oculta até ser necessária. O arquivo [templates/fragments/confirmation.html]:

<!--/* uma única janela para a página inteira, oculta (d-none) no início */-->
<div id="confirmation-modal" 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="confirmation-modal-message"></p>
        </div>
        <div class="modal-footer">
          <button type="button" class="btn btn-secondary" data-action="no">No, go back</button>
          <button type="button" class="btn btn-danger" data-action="yes">Yes, confirm</button>
        </div>
      </div>
    </div>
  </div>
</div>
  • linha 2: um fragmento sem parâmetros. A classe [d-none] oculta a janela;
  • linha 3: o fundo cinza;
  • linha 11: o local da pergunta;
  • linhas 14 e 15: os dois botões, identificados pelo atributo [data-action].

O arquivo [templates/layout.html]:

<!doctype html>
<html lang="en" xmlns:th="http://www.thymeleaf.org" th:fragment="page(content)">
<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="${content}"></main>
  </div>
  <!--/* a janela de confirmação, presente em todas as páginas */-->
  <div th:replace="~{fragments/confirmation :: confirmation}"></div>
  <!--/* o script, no final da página: os elementos que ele procura já existem */-->
  <script src="/js/app.js"></script>
</body>
</html>
  • linha 11: a mensagem flash;
  • linha 15: a janela aparece em todas as páginas;
  • linha 17: o script é carregado no final da página; quando ele é executado, os elementos que ele procura já existem. Ele é servido como arquivo estático a partir de [static/js/app.js].

Uma pequena porção de [JavaScript] vincula os formulários à janela. O arquivo [static/js/app.js]:

// confirmação dos formulários que carregam o atributo data-confirmation="..."
// Sem JavaScript, esses formulários são simplesmente enviados sem confirmação.
(() => {
  const modal = document.getElementById('confirmation-modal');
  const message = document.getElementById('confirmation-modal-message');
  let pending = null; // o formulário a enviar se o usuário confirmar

  // 1. interceptamos o envio dos formulários a confirmar
  document.querySelectorAll('form[data-confirmation]').forEach((form) => {
    form.addEventListener('submit', (event) => {
      event.preventDefault(); // o envio é suspenso
      pending = form;
      message.textContent = form.dataset.confirmation;
      modal.classList.remove('d-none'); // a janela aparece
    });
  });

  // 2. os dois botões da janela
  modal.addEventListener('click', (event) => {
    const action = event.target.dataset.action;
    if (action === 'yes') {
      pending.submit(); // envio, SEM disparar novamente o evento 'submit'
    } else if (action === 'no') {
      modal.classList.add('d-none');
      pending = null;
    }
  });
})();
  • linha 3: o código é envolvido em uma função que é executada imediatamente, para evitar a criação de variáveis globais;
  • linhas 9 a 16: o envio de cada formulário que tenha o atributo [data-confirmation] é interceptado. [preventDefault()] suspende o envio; o formulário é guardado, a pergunta é colocada na janela ([textContent], e não [innerHTML]: a pergunta é exibida como texto, nunca interpretada como HTML), e a janela é exibida;
  • Linhas 19 a 27: “Yes” envia o formulário guardado. O método [submit()] de um formulário o envia sem disparar o evento [submit]: não há uma nova solicitação de confirmação. “No” oculta a janela.

Se o [JavaScript] estiver desativado, os formulários são simplesmente enviados sem confirmação: a aplicação continua funcionando. Esse é o princípio do aprimoramento incremental: o [JavaScript] acrescenta conveniência, mas não é essencial. O estudo de caso segue esse princípio (seu script [static/js/app.js] acrescenta o tratamento do teclado: tecla Esc, foco). As páginas resultantes, a partir de http://localhost:5000/contacts: a lista, a solicitação de confirmação, a lista após a exclusão e o perfil de um contato:

Image

Image

Image

Image

Por fim, verificamos que a exclusão não pode ser disparada por uma requisição GET:

curl -i http://localhost:5000/contacts/2/delete
1
2
3
4
5
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/delete"}

O caminho existe, mas não para o método GET: o [Spring MVC] retorna [405 Method Not Allowed], e o cabeçalho [Allow] indica o método aceito. O corpo da resposta é a resposta de erro do [Spring Boot], como visto em JSON para o [curl] (um navegador que solicita HTML recebe uma página de erro). Com POST:

curl -i -X POST http://localhost:5000/contacts/2/delete
1
2
3
4
HTTP/1.1 302
Set-Cookie: JSESSIONID=A9EDA1129B98CE1244D75669371DA9B0; Path=/; HttpOnly
Location: http://localhost:5000/contacts
Content-Length: 0

A exclusão ocorreu, seguida de um redirecionamento para a lista; o cookie [JSESSIONID] é o cookie de sessão que transporta a mensagem flash. E um contato inexistente:

curl -i http://localhost:5000/contacts/99
1
2
3
4
HTTP/1.1 404
Content-Type: application/json

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

A resposta 404 repete o motivo informado para a exceção [ResponseStatusException] ([unknown contact]). Esse campo, [message], só está presente durante o desenvolvimento: as ferramentas de desenvolvimento do [Spring Boot] ([devtools], uma dependência de todos os exemplos) ativam sua exibição; sem elas, a resposta contém apenas o código, o erro e o caminho.