Thymeleaf Java: دليل شامل، أمثلة وتثبيت

ما هو Thymeleaf ولماذا نستخدمه؟

Thymeleaf هو محرك قوالب (Template Engine) حديث يعمل على الخادم لتطبيقات Java، ومصمم لتوليد ملفات HTML وXML وJavaScript وCSS والنصوص. على عكس JSP (JavaServer Pages)، يقدم Thymeleaf صياغة (syntax) أنظف وأكثر قابلية للقراءة وطبيعية، يسهل فهمها من قبل المطورين ومصممي الواجهات على حد سواء.

الميزة الأساسية لـ Thymeleaf هي أن قوالبه تُعتبر مستندات HTML صالحة. هذا يعني أنه يمكنك فتح القالب في المتصفح دون تشغيل الخادم ورؤية هيكله. يتم إدراج البيانات الديناميكية باستخدام سمات خاصة تبدأ بالبادئة th:.

يتكامل Thymeleaf بشكل مثالي مع إطار Spring Framework (خاصة Spring Boot)، ويمكن استخدامه أيضاً كمكتبة مستقلة. يدعم التخطيطات (layouts)، والأجزاء (fragments)، والجمل الشرطية، والحلقات التكرارية، والعمل مع النماذج، والتدويل (i18n)، وغيرها الكثير.

تثبيت Thymeleaf

بما أن Thymeleaf هي مكتبة Java، يتم تثبيتها عبر أنظمة إدارة التبعيات مثل Maven أو Gradle. لا يوجد ما يعادل pip install في Java.

التثبيت عبر Maven (ملف pom.xml)

<dependency>
    <groupId>org.thymeleaf</groupId>
    <artifactId>thymeleaf</artifactId>
    <version>3.1.2.RELEASE</version>
</dependency>

التثبيت عبر Gradle (ملف build.gradle)

implementation 'org.thymeleaf:thymeleaf:3.1.2.RELEASE'

لـ Spring Boot (موصى به)

إذا كنت تستخدم Spring Boot، يكفي إضافة المُشغّل (starter) التالي:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>

سيقوم Spring Boot تلقائياً بتكوين Thymeleaf بالإعدادات الافتراضية المناسبة.

بداية سريعة مع مثال عملي

لنقم بإنشاء تطبيق بسيط يعمل من سطر الأوامر ويستخدم Thymeleaf لتوليد HTML.

الخطوة 1: إنشاء قالب (src/main/resources/templates/hello.html)

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <title>مرحباً Thymeleaf</title>
</head>
<body>
    <h1 th:text="${message}">النص الافتراضي</h1>
    <p>التاريخ الحالي: <span th:text="${#dates.format(#dates.createNow(), 'dd-MM-yyyy')}">01-01-2024</span></p>
</body>
</html>

الخطوة 2: كتابة كود Java لمعالجة القالب

import org.thymeleaf.TemplateEngine;
import org.thymeleaf.context.Context;
import org.thymeleaf.templateresolver.ClassLoaderTemplateResolver;

public class ThymeleafQuickStart {
    public static void main(String[] args) {
        // 1. إعداد محلل القوالب
        ClassLoaderTemplateResolver resolver = new ClassLoaderTemplateResolver();
        resolver.setPrefix("/templates/");
        resolver.setSuffix(".html");
        resolver.setTemplateMode("HTML");

        // 2. إنشاء محرك القوالب
        TemplateEngine engine = new TemplateEngine();
        engine.setTemplateResolver(resolver);

        // 3. إنشاء سياق يحتوي على البيانات
        Context context = new Context();
        context.setVariable("message", "مرحباً بك في Thymeleaf!");

        // 4. معالجة القالب
        String result = engine.process("hello", context);
        
        System.out.println(result);
    }
}

النتيجة بعد التنفيذ:

<!DOCTYPE html>
<html>
<head>
    <title>مرحباً Thymeleaf</title>
</head>
<body>
    <h1>مرحباً بك في Thymeleaf!</h1>
    <p>التاريخ الحالي: <span>15-03-2024</span></p>
</body>
</html>