Trabalhando com fragmentos no Thymeleaf

1. Visão geral

Neste tutorial, mostraremos comomake use of Thymeleaf Fragments to reuse some common parts of a site. Depois de configurar um projeto Spring MVC muito simples, vamos nos concentrar nas visualizações.

Se você é novo no Thymeleaf, pode verificar outros artigos neste site, comothis introduction, bem comothis one about the 3.0 version do mecanismo.

2. Dependências do Maven

Precisaremos de algumas dependências para habilitar o Thymeleaf:


    org.thymeleaf
    thymeleaf
    3.0.9.RELEASE


    org.thymeleaf
    thymeleaf-spring5
    3.0.9.RELEASE

A versão mais recente dethymeleafethymeleaf-spring5 pode ser encontrada no Maven Central.

3. Projeto Primavera

3.1. Configuração do Spring MVC

Para habilitar o Thymeleaf e definir o sufixo do modelo, precisamosconfigure MVC with a view resolver and template resolver.

Também definiremos o diretório para alguns recursos estáticos:

@Bean
public ViewResolver htmlViewResolver() {
    ThymeleafViewResolver resolver = new ThymeleafViewResolver();
    resolver.setTemplateEngine(templateEngine(htmlTemplateResolver()));
    resolver.setContentType("text/html");
    resolver.setCharacterEncoding("UTF-8");
    resolver.setViewNames(ArrayUtil.array("*.html"));
    return resolver;
}

private ITemplateResolver htmlTemplateResolver() {
    SpringResourceTemplateResolver resolver
      = new SpringResourceTemplateResolver();
    resolver.setApplicationContext(applicationContext);
    resolver.setPrefix("/WEB-INF/views/");
    resolver.setCacheable(false);
    resolver.setTemplateMode(TemplateMode.HTML);
    return resolver;
}

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/resources/**", "/css/**")
      .addResourceLocations("/WEB-INF/resources/", "/WEB-INF/css/");
}

Observe que se estivermos usando Spring Boot, esta configuração pode não ser necessária, a menos que precisemos aplicar nossas próprias personalizações.

3.2. O controlador

Nesse caso, o controlador é apenas um veículo para as visualizações. Cada visualização mostra um cenário de uso de fragmento diferente.

O último carrega alguns dados que são passados pelo modelo a serem exibidos na visualização:

@Controller
public class FragmentsController {

    @GetMapping("/fragments")
    public String getHome() {
        return "fragments.html";
    }

    @GetMapping("/markup")
    public String markupPage() {
        return "markup.html";
    }

    @GetMapping("/params")
    public String paramsPage() {
        return "params.html";
    }

    @GetMapping("/other")
    public String otherPage(Model model) {
        model.addAttribute("data", StudentUtils.buildStudents());
        return "other.html";
    }
}

Note that the view names must contain the “.html” suffix because of the way we configured our resolver. Também especificaremos o sufixo quando nos referirmos aos nomes dos fragmentos.

4. As visualizações

4.1. Inclusão de fragmento simples

Primeiro, usaremos reutilizar partes comuns em nossas páginas.

Podemos definir essas partes como fragmentos, em arquivos isolados ou em uma página comum. Neste projeto, essas peças reutilizáveis são definidas em uma pasta chamadafragments.

Existem três maneiras básicas de incluir o conteúdo de um fragmento:

insert – insere conteúdo dentro da tag
replace – substitui a marca atual pela marca que define o fragmento
include – está obsoleto, mas ainda pode aparecer em um código legado

O próximo exemplo,fragments.html, mostra o uso de todas as três maneiras. Este modelo Thymeleaf adiciona fragmentos na cabeça e no corpo do documento:




Thymeleaf Fragments: home



     
    Go to the next page to see fragments in action

Now, let’s take a look at a page that holds some fragments. É chamadogeneral.html, e é como uma página inteira com algumas partes definidas como fragmentos prontos para serem usados:








    
        Thymeleaf Fragments sample
    
    Go to the next page to see fragments in action
    
        This is a sidebar
    
    This is another sidebar
    
        Fragments Index |
        Markup inclussion |
        Fragment params |
        Other

A seção<head> contém apenas uma folha de estilo, mas podemos aplicar outras ferramentas, como Bootstrap, jQuery ou Foundation, diretamente ou usando Webjars.

Observe que todas as tags reutilizáveis deste modelo têm o atributoth:fragment, mas a seguir veremos como incluir qualquer outra parte da página.

Após a inclusão da renderização e dos fragmentos, o conteúdo retornado é:




Thymeleaf Fragments: home




    
        
            Thymeleaf Fragments sample
        
    
    Go to the next page to see fragments in action
    
        Fragments Index |
        Markup inclussion |
        Fragment params |
        Other

4.2. Seletores de marcação para fragmentos

Uma das melhores coisas sobre os fragmentos de folha do timo é quewe can also grab any part of a template just using the simple selectors, por meio de classes, ids ou simplesmente por tags.

Esta página, por exemplo, inclui alguns componentes do arquivogeneral.html: um blocoaside e o blocodiv.another:

4.3. Fragmentos Parametrizados

Podemos passar parâmetros para um fragmento para alterar alguma parte específica dele. Para fazer isso, o fragmento deve ser definido como uma chamada de função, onde devemos declarar uma lista de parâmetros.

Neste exemplo, definimos um fragmento para um campo de formulário genérico:


    
         Field

E aqui está um uso simples desse fragmento, onde passamos parâmetros para ele:

E é assim que o campo retornado ficará:


    
         Name

4.4. Expressões de inclusão de fragmento

Os fragmentos de folha timbrada oferecem outras opções interessantes, como suporte paraconditional expressions to determine whether to include a fragment.

Usando o operadorElvis com qualquer uma das expressões fornecidas pelo Thymeleaf (segurança, strings e coleções, por exemplo), somos capazes de carregar fragmentos diferentes.

Por exemplo, podemos definir esse fragmento com algum conteúdo que mostraremos dependendo de uma determinada condição. Pode ser um arquivo que contém diferentes tipos de blocos:

Data received
No data

E é assim que podemos carregá-los com uma expressão:

Para saber mais sobre as expressões do Thymeleaf, verifique nosso artigohere.

4.5. Layouts Flexíveis

O próximo exemplo também mostra dois outros usos interessantes de fragmentos pararender a table with data. Este é o fragmento reutilizável da tabela, com duas partes importantes: um cabeçalho da tabela que pode ser alterado e o corpo em que os dados são renderizados:


0	Name

Quando queremos usar esta tabela, podemos passar nosso próprio cabeçalho de tabela usando a funçãofields. O cabeçalho é referenciado com a classemyFields. O corpo da tabela é carregado passando dados como um parâmetro para a funçãotableBody:

E é assim que a página final ficará:


    
        Thymeleaf Fragments sample
    
    Data received
    
        
            

                Id
                Name
            
        
        
            
                1001
                John Smith
            
            
                1002
                Jane Williams
            
        
    
    
        Fragments Index |
        Markup inclussion |
        Fragment params |
        Other

Id	Name
1001	John Smith
1002	Jane Williams

5. Conclusão

Neste artigo, mostramos como reutilizar componentes de visualização por meio do uso de Thymeleaf Fragments, uma ferramenta poderosa que pode facilitar o gerenciamento de modelos.

Também apresentamos alguns outros recursos interessantes que vão além do básico. Devemos levar isso em consideração ao escolher o Thymeleaf como nosso mecanismo de renderização de exibição.

Se você quiser aprender sobre outros recursos do Thymeleaf, você definitivamente deve dar uma olhada em nosso artigo sobreLayout Dialects.

Como sempre, o código de implementação completo do exemplo está disponívelover on GitHub.

TOC

Trabalhando com fragmentos no Thymeleaf