Thymeleaf - Quick Reference

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: thymeleaf for comprehensive documentation.

Pattern Essenziali

Basic Syntax

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <title th:text="${title}">Default</title>
</head>
<body>
    <h1 th:text="${message}">Hello</h1>
    <p th:text="'Welcome, ' + ${name}">Welcome, User</p>
</body>
</html>

Variables & Loops

<!-- Variable -->
<p th:text="${user.name}">Name</p>

<!-- Loop -->
<tr th:each="user : ${users}">
    <td th:text="${user.name}">Name</td>
    <td th:text="${user.email}">Email</td>
</tr>

<!-- Conditionals -->
<p th:if="${user.active}">Active</p>
<p th:unless="${user.active}">Inactive</p>

Email Service

@Service
@RequiredArgsConstructor
public class EmailService {

    private final TemplateEngine templateEngine;
    private final JavaMailSender mailSender;

    public void sendWelcome(User user) {
        Context ctx = new Context();
        ctx.setVariable("userName", user.getName());
        ctx.setVariable("actionUrl", "https://app.com/verify");

        String html = templateEngine.process("emails/welcome", ctx);

        MimeMessage msg = mailSender.createMimeMessage();
        MimeMessageHelper helper = new MimeMessageHelper(msg, true);
        helper.setTo(user.getEmail());
        helper.setSubject("Welcome!");
        helper.setText(html, true);
        mailSender.send(msg);
    }
}

Fragments & Layouts

<!-- fragments/common.html -->
<nav th:fragment="navigation">
    <ul>
        <li><a th:href="@{/}">Home</a></li>
        <li><a th:href="@{/about}">About</a></li>
    </ul>
</nav>

<footer th:fragment="footer(year)">
    <p th:text="'© ' + ${year} + ' My Company'">© 2024 My Company</p>
</footer>

<!-- Usage: th:replace vs th:insert -->
<!-- th:replace - replaces host tag completely -->
<div th:replace="~{fragments/common :: navigation}"></div>

<!-- th:insert - inserts fragment inside host tag -->
<div th:insert="~{fragments/common :: navigation}"></div>

<!-- With parameters -->
<div th:replace="~{fragments/common :: footer(${#dates.year(#dates.createNow())})}"></div>

Layout Dialect

<!-- pom.xml -->
<dependency>
    <groupId>nz.net.ultraq.thymeleaf</groupId>
    <artifactId>thymeleaf-layout-dialect</artifactId>
</dependency>

<!-- layouts/main.html -->
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org"
      xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout">
<head>
    <title layout:title-pattern="$CONTENT_TITLE - $LAYOUT_TITLE">My App</title>
    <link rel="stylesheet" th:href="@{/css/main.css}"/>
</head>
<body>
    <header th:replace="~{fragments/common :: navigation}"></header>

    <main layout:fragment="content">
        <!-- Page content goes here -->
    </main>

    <footer th:replace="~{fragments/common :: footer}"></footer>

    <script layout:fragment="scripts"></script>
</body>
</html>

<!-- pages/home.html -->
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org"
      xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout"
      layout:decorate="~{layouts/main}">
<head>
    <title>Home</title>
</head>
<body>
    <main layout:fragment="content">
        <h1>Welcome!</h1>
        <p th:text="${message}">Content</p>
    </main>

    <th:block layout:fragment="scripts">
        <script th:src="@{/js/home.js}"></script>
    </th:block>
</body>
</html>

Form Binding

<form th:action="@{/users}" th:object="${userForm}" method="post">
    <div>
        <label for="name">Name:</label>
        <input type="text" id="name" th:field="*{name}"
               th:classappend="${#fields.hasErrors('name')} ? 'error' : ''"/>
        <span th:if="${#fields.hasErrors('name')}"
              th:errors="*{name}" class="error-msg">Name error</span>
    </div>

    <div>
        <label for="email">Email:</label>
        <input type="email" id="email" th:field="*{email}"/>
        <span th:if="${#fields.hasErrors('email')}"
              th:errors="*{email}" class="error-msg">Email error</span>
    </div>

    <div>
        <label for="role">Role:</label>
        <select id="role" th:field="*{role}">
            <option value="">-- Select --</option>
            <option th:each="role : ${roles}"
                    th:value="${role}"
                    th:text="${role.displayName}">Role</option>
        </select>
    </div>

    <button type="submit">Save</button>
</form>

JavaScript Inlining

<script th:inline="javascript">
    // Natural templates with fallback
    const user = /*[[${user}]]*/ { name: 'default' };
    const userId = /*[[${user.id}]]*/ 0;
    const isAdmin = /*[[${user.admin}]]*/ false;

    // Array
    const items = /*[[${items}]]*/ [];

    // Conditional in JS
    /*[# th:if="${user != null}"]*/
    console.log('User:', user.name);
    /*[/]*/
</script>

<!-- CSS inlining -->
<style th:inline="css">
    .user-bg {
        background-color: [[${user.favoriteColor}]];
    }
</style>

Utility Objects

<!-- Dates -->
<p th:text="${#dates.format(user.createdAt, 'dd/MM/yyyy HH:mm')}">Date</p>
<p th:text="${#dates.dayOfWeekName(date)}">Monday</p>

<!-- Strings -->
<p th:text="${#strings.toUpperCase(name)}">NAME</p>
<p th:text="${#strings.abbreviate(text, 100)}">Truncated...</p>
<p th:text="${#strings.isEmpty(value) ? 'N/A' : value}">Value</p>
<p th:text="${#strings.listJoin(items, ', ')}">a, b, c</p>

<!-- Numbers -->
<p th:text="${#numbers.formatDecimal(price, 1, 2)}">10.50</p>
<p th:text="${#numbers.formatCurrency(amount)}">$1,234.56</p>

<!-- Lists -->
<p th:text="${#lists.size(users)}">Count</p>
<p th:if="${#lists.isEmpty(users)}">No users</p>
<p th:text="${#lists.contains(roles, 'ADMIN')}">Has admin</p>

<!-- Aggregates -->
<p th:text="${#aggregates.sum(prices)}">Total</p>
<p th:text="${#aggregates.avg(scores)}">Average</p>

Switch/Case

<div th:switch="${user.role}">
    <p th:case="'ADMIN'">Administrator</p>
    <p th:case="'MANAGER'">Manager</p>
    <p th:case="'USER'">Regular User</p>
    <p th:case="*">Unknown Role</p>
</div>

Iteration Status

<tr th:each="user, stat : ${users}"
    th:class="${stat.odd} ? 'odd' : 'even'">
    <td th:text="${stat.index}">0</td>
    <td th:text="${stat.count}">1</td>
    <td th:text="${user.name}">Name</td>
    <td th:if="${stat.first}">First!</td>
    <td th:if="${stat.last}">Last!</td>
</tr>

Expressions

| Expr | Uso | |------|-----| | ${var} | Variable | | *{prop} | Selection (con th:object) | | @{/url} | Link URL | | #{msg} | Message i18n | | ~{frag} | Fragment |

Best Practices

| Do | Don't | |----|-------| | Use th:text for escaped output | Use th:utext with user input (XSS) | | Use fragments for reusable components | Duplicate HTML across templates | | Keep templates simple | Put complex logic in templates | | Use i18n messages | Hardcode text strings | | Use layout dialects | Repeat layout in every page |

When NOT to Use This Skill

REST APIs - Use spring-rest skill for JSON responses
SPA frontends - Use React, Vue, or Angular
PDF reports - Use JasperReports or iText
High-traffic APIs - Consider static frontends

Anti-Patterns

| Anti-Pattern | Problem | Solution | |--------------|---------|----------| | th:utext with user input | XSS vulnerability | Use th:text for escaping | | Complex logic in templates | Hard to test, maintain | Move logic to controller | | Missing th namespace | Silent failures | Always declare xmlns:th | | Inline styles everywhere | Inconsistent UI | Use CSS classes | | No fragment reuse | Code duplication | Extract common fragments |

Quick Troubleshooting

| Problem | Diagnostic | Fix | |---------|------------|-----| | Variables not rendering | Check th: prefix | Use th:text, th:value | | Template not found | Check path | Place in templates/ folder | | Iteration not working | Check th:each syntax | Verify collection is passed | | Fragments not included | Check path syntax | Use ~{fragments/name :: fragment} | | i18n not working | Check messages.properties | Verify file location and keys |