How thymeleaf layout:decorator works

user_6595903 0
Viewed 15241

I have come across a piece of code in a springboot (1.3.2) - thymeleaf (2.1.4) - thymeleaf layout dialect (1.3.1) project I'm working where the content html file contains:

<html xmlns:th="http://www.thymeleaf.org" layout:decorator="layout/sitelayout">
...

<div th:fragment="content" class="container">
....
</div>

And the sitelayout.html file contains:

<div layout:fragment="content">
    <h1>Static content for prototyping purposes only</h1>

    <p>
        This is the layout of the site. The actual content will come from individual views making use of this layout
    </p>
</div>

===================================================

I searched the web and could not find enough information / documentation example about how it works. Can someone point me to the right direction?

thymeleaf spring-boot
4 Answers

A Comprehensive Description:

You know that the Thymeleaf is a Template Engine and uses several concepts:

  • Template:
     Template is a concept and means that you can write your html files more generally (maybe including other templates). These template files finally will be processed by the Thymeleaf template engine in server side and creates a regular html file that will be send to the client.
  • Layout (a general concept):
    Layout refers to the arrangement of text, images and other objects on a page, and it is the most interested matter of website designers. By the layout concept, you can specify overall structure/formatting of your pages. The layout files can be without content (only structure), or with some content that is shared by its callers.
  • Layout template (= Page Layout):
    Layout template refers to a layout file with several fragments and empty tags, so that the layout callers (page templates) calls it and use its structure (while themselves have content also).
  • Page template:
    Page template refers to html file of a page, so that can call other templates and fragments and use the layout template's structure. The page template finally will be converted to a regular html page by the Thymeleaf template engine.
  • Fragment:
     Fragment is a part of a Template. Thymeleaf allows you to import fragments of a Template into another Template.

Usually, developers create several layout templates (for different page formats) that will be shared across other page templates. The layout/page templates often contains some fragments such as page header, navigation, footer, and a main section where your main content will go.

Now what is dialect? As you know, Thymeleaf is a tool allowing customization and for this purpose, Dialect allows you define how your Template will be processed. In fact the Layout dialect performs decoration as per the decorator pattern.

Different Dialects:

  1. The core library of Thymeleaf provides a dialect called Standard
    Dialect    , which is enough for use for everyone and uses OGNL
    language to proccess a template.
  2. Spring Framework creates a private dialect called SpringStandard Dialect. it is like the Thymeleaf standard dialect, but has minor adjustments for better use of some features in Spring Framework. For example: It uses Spring Expression Language (SpringEL) instead of using OGNL. Therefore, if use Spring Framework, you should use this dialect.
  3. thymeleaf-layout-dialect : which is a open source project and has more features that lets you build layouts and reusable templates in order to improve code reuse. This library uses layout: prefix for its attributes.
  4. Custom Dialect: You can extends the Thymeleaf and create your own dialect.

Example: The thymeleaf in spring boot project with thymeleaf-layout-dialect(dialect number 3):

 <dependency>
         <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-thymeleaf</artifactId>
        </dependency>
        <dependency>
            <groupId>nz.net.ultraq.thymeleaf</groupId>
            <artifactId>thymeleaf-layout-dialect</artifactId>
        </dependency>
 </dependency>

Note: The reason of decorator OR decorate in dialect number (3):
The Thymeleaf layout dialect version 1.x uses the decorator which was opposite to the decorator pattern.
So in the version 2.x, this mistake by introducing the decorate was solved.
Therefore although the Thymeleaf and its layout dialect libraries are backward-compatible, but it is better that use layout:decorate in your codes.

While the layout dialect does perform decoration as per the decorator pattern, throughout 1.x it incorrectly identified the layout/parent template as the decorator, when instead, according to the design pattern, the extension (content template in this case) is the decorator. This change is simply a rename of the layout:decorator/data-layout-decorator processor to layout:decorate/data-layout-decorate so that the template being specified is the one being decorated, not the decorator, plus an overhaul of the documentation to fix this inconsistency.
ref: https://ultraq.github.io/thymeleaf-layout-dialect/MigrationGuide.html
So, you have to use the layout:decorate in your page templates and refer it to the main template.
The layout:decorate in the tag says which layout template to decorate using this content template


Example: https://ultraq.github.io/thymeleaf-layout-dialect/Examples.html#layouts

user_109760880

Usually websites share common page components like the header, footer, menu and possibly many more. These page components can be used by the same or different layouts. There are two main styles of organizing layouts in projects: include style and hierarchical style. Both styles can be easily utilized with Thymeleaf without losing its biggest value: natural templating.

Source: http://www.thymeleaf.org/doc/articles/layouts.html

user_75611290
Related