新人と先輩の会話形式で理解しよう

新人

「先輩、Spring Bootで使われているThymeleafって何ですか？テンプレートエンジンって言われても、いまいちピンとこないです。」

先輩

「Thymeleaf（タイムリーフ）は、HTMLにJavaのデータを埋め込んで動的に画面を作るためのテンプレートエンジンだよ。Spring MVCでよく使われているんだ。」

新人

「なるほど！HTMLにJavaの値を表示できるんですね。どうやってデータを渡すんですか？」

先輩

「良い質問だね。では、まずThymeleafとは何かをしっかり理解してから、変数の扱い方や定義方法を見ていこう。」

1. Thymeleafとは何か（テンプレートエンジンの概要）

Thymeleafは、Javaで作った値をHTMLの中に埋め込むためのテンプレートエンジンです。Spring BootやSpring MVCの標準ビューとして利用されており、サーバーサイドで生成したデータをHTML画面に簡単に反映できます。テンプレートエンジンとは、静的なHTMLファイルに動的な値を差し込む仕組みのことを指します。

例えば、サーバー側で取得したユーザー名や商品情報などを、Thymeleafを使ってHTMLの中に出力できます。JSPと似ていますが、ThymeleafはHTML構文に沿って記述できるのが特徴で、HTMLファイルとして直接ブラウザで確認できる点が便利です。

Thymeleafを導入すると、開発者はHTMLを保ちながらサーバー側の変数を自然に扱えるため、テンプレートエンジンの中でも特に人気があります。

2. Thymeleafで変数を扱う目的（HTMLとの連携や表示の仕組み）

Thymeleafでは、HTMLとJavaのデータを連携させるために「変数」を利用します。この変数は、サーバー側のSpringコントローラから渡された値をHTML内で表示するための橋渡し役です。

たとえば、Springの@ControllerクラスでModelオブジェクトを使ってデータを渡すと、Thymeleafテンプレートで${}構文を用いてその値を取得できます。これによって、動的に値を埋め込むことができます。

基本的には、コントローラがHTMLにデータを渡す → ThymeleafがそれをHTML内で表示、という流れです。

では、具体的にどのように変数を定義して使うのか、順を追って見ていきましょう。

3. コントローラからThymeleafにデータを渡す流れの全体像

Thymeleafで変数を使うには、まずSpringのコントローラ側で値を準備し、それをModelオブジェクト経由でテンプレートに渡します。このときに使うのがModelクラスです。pleiadesでGradleプロジェクトを作成すれば、必要な依存関係も簡単に追加できます。

次のコードは、Springのコントローラで変数を定義し、Thymeleafに渡す基本的な例です。


package com.example.demo.controller;

import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class HelloController {

    @GetMapping("/hello")
    public String hello(Model model) {
        model.addAttribute("name", "田中太郎");
        return "hello";
    }
}

上記では、Modelに「name」という変数を追加し、値として「田中太郎」を設定しています。この変数は、ThymeleafのHTMLテンプレートで呼び出すことができます。

次に、Thymeleaf側で変数を表示するHTMLを書いてみましょう。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>Hello Page</title>
</head>
<body>
    <h1 th:text="'こんにちは、' + ${name} + 'さん！'">こんにちは、ゲストさん！</h1>
</body>
</html>

このHTMLでは、th:text属性を使って${name}変数を展開しています。結果として、ブラウザには「こんにちは、田中太郎さん！」と表示されます。


こんにちは、田中太郎さん！

このように、Thymeleafでは変数を通してサーバーサイドの値をHTMLに反映できます。これがThymeleaf変数定義の基本的な流れです。

次の記事では、th:withを使ったローカル変数の定義方法や、スコープを意識した使い分けをさらに詳しく解説していきます。

4. Thymeleafで変数を定義する方法（th:withやローカル変数の使い方）

Thymeleafでは、ページ全体で使う変数だけでなく、一時的に使う「ローカル変数」を定義することもできます。このときに利用するのがth:with属性です。th:withを使うことで、テンプレートの中に一時的な変数を作成し、複雑な式を整理したり、見やすくしたりすることができます。

例えば、複数の変数を組み合わせて表示したい場合に、いちいち${}の中で計算を書くと読みづらくなります。そんなときにth:withを使えば、HTMLの一部で一時的な変数を定義して扱えます。


<div th:with="greeting='こんにちは', userName=${name}">
    <p th:text="${greeting} + '、' + ${userName} + 'さん！'">こんにちは、ゲストさん！</p>
</div>

このようにth:withの中で複数の変数を定義できます。上記の例では、greetingとuserNameをローカル変数として扱っています。変数はカンマ区切りで複数指定でき、定義したブロック内でのみ有効です。

この仕組みを使うと、同じテンプレート内で何度も同じ式を書く必要がなくなり、コードの保守性が上がります。Thymeleafのth:withは、HTML構造を保ちながらロジックを分かりやすく整理できる便利な機能です。

新人

「なるほど、th:withを使うと一時的な変数を作れるんですね。でも、Modelで渡した変数とは違うんですか？」

先輩

「そうだね。Modelで渡すのはコントローラからテンプレートに渡す全体的な変数で、th:withで定義するのはテンプレート内だけで使うローカル変数なんだ。使い分けることで、コードが整理されて読みやすくなるよ。」

5. コントローラからModelに値を渡す方法（@Controller＋Modelオブジェクト）

Thymeleafの変数は、コントローラで定義したModelオブジェクトを介してテンプレートに渡されます。Modelとは、サーバーからビューにデータを送るためのオブジェクトで、Spring MVCでは最も基本的なデータ受け渡しの仕組みです。

pleiadesを使ってGradleプロジェクトを作成している場合、Spring Boot Starter Thymeleafを依存関係として追加すれば、自動的にThymeleafがビューとして設定されます。

次の例では、複数の変数をModelに追加してThymeleafに渡しています。


package com.example.demo.controller;

import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class SampleController {

    @GetMapping("/user")
    public String user(Model model) {
        model.addAttribute("name", "山田花子");
        model.addAttribute("age", 28);
        model.addAttribute("city", "東京");
        return "user";
    }
}

上記のコードでは、ユーザー名・年齢・都市をそれぞれ変数としてModelに登録しています。これらの値は、Thymeleafテンプレート内で${name}や${age}のように参照できます。

この方法によって、サーバーサイドで処理したデータをHTMLに動的に表示できるようになります。例えば、ユーザー情報や商品リスト、検索結果なども同じ仕組みで扱えます。

新人

「Modelにデータを入れると、それがThymeleafで表示できるようになるんですね！じゃあ、Modelに入れなかった変数は使えないんですか？」

先輩

「その通り。Modelに追加していないデータはThymeleaf側では認識できないよ。必要なデータはすべてModelを通して渡すのが基本ルールだね。」

6. HTML側で変数を参照する方法（${}式の使い方）

ThymeleafのHTMLテンプレートでは、変数を${}構文を使って参照します。この構文はEL式と呼ばれ、Modelから渡されたデータをテンプレート内で取り出すための基本的な書き方です。

次の例では、コントローラから渡された3つの変数をHTMLに出力しています。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>User Info</title>
</head>
<body>
    <h1 th:text="'ユーザー情報'">ユーザー情報</h1>
    <p>名前：<span th:text="${name}">ゲスト</span></p>
    <p>年齢：<span th:text="${age}">0</span>歳</p>
    <p>居住地：<span th:text="${city}">未設定</span></p>
</body>
</html>

このコードでは、th:text属性を使ってそれぞれの変数を表示しています。Modelから渡された値がHTMLに自動的に反映され、動的な画面が生成されます。


ユーザー情報
名前：山田花子
年齢：28歳
居住地：東京

このように、Thymeleafでは変数を簡単に埋め込むことができるため、画面表示の仕組みをJavaコードから分離できます。HTMLデザイナーとエンジニアが分業しやすいのもThymeleafの魅力です。

また、${}式はオブジェクトのプロパティにもアクセスできます。たとえば、ModelにUserオブジェクトを追加した場合、${user.name}や${user.email}のようにドット記法で値を取得できます。


model.addAttribute("user", new User("佐藤次郎", "jiro@example.com"));


<p th:text="${user.name}">名前</p>
<p th:text="${user.email}">メール</p>

このように、Thymeleafの変数参照構文はシンプルでわかりやすく、SpringのModelとの連携もスムーズです。初心者でも仕組みを理解すれば、テンプレートを自由にカスタマイズできるようになります。

次の記事では、Thymeleafの変数スコープやセッションとの関係について、もう一歩踏み込んで解説していきます。

7. 変数スコープの考え方（リクエストスコープ・セッションスコープ・アプリケーションスコープ）

Thymeleafでは、変数を扱う際に「スコープ」という概念を理解しておくことが大切です。スコープとは、変数がどの範囲で有効かを表す仕組みのことです。例えば、ある画面だけで使える変数もあれば、ログイン中ずっと保持したい変数もあります。これを制御するのがスコープの役割です。

Spring MVCでよく使われるスコープには、主に「リクエストスコープ」「セッションスコープ」「アプリケーションスコープ」の3種類があります。

リクエストスコープは、1回のリクエスト内だけで有効な変数です。ページを再読み込みしたり、別のURLに移動したりすると値は消えます。最もよく使われるスコープで、Modelで渡す変数は基本的にこのスコープに属します。

セッションスコープは、ユーザーごとに保持されるスコープです。ログイン情報や一時的な状態を保持したい場合に使われ、ブラウザを閉じるまで値が保持されます。

アプリケーションスコープは、アプリ全体で共有されるスコープです。全ユーザーで共通の設定値や統計データなどを扱うときに利用されます。

新人

「なるほど！スコープによって変数が生きている範囲が違うんですね。でも、Thymeleafでどうやってスコープを区別するんですか？」

先輩

「良い質問だね。Thymeleafでは、${}の前にスコープ名を付けることで明示的に指定できるんだ。例えば${session.userName}のように書けば、セッションスコープの変数を参照できるよ。」

8. スコープごとの使い分け例（リクエスト属性とセッション属性の実践）

それでは実際に、リクエストスコープとセッションスコープの使い分けを見てみましょう。まずはリクエストスコープです。これは通常のModelを使って値を渡す方法で、ページの再表示のたびに新しい値が渡されます。


@GetMapping("/request-scope")
public String requestScope(Model model) {
    model.addAttribute("message", "リクエストスコープの値です");
    return "scope";
}

次に、セッションスコープを使う場合はHttpSessionを利用します。セッションスコープの変数は、ユーザーがサイトを利用している間ずっと保持されるため、ログイン状態の管理などに便利です。


@GetMapping("/session-scope")
public String sessionScope(HttpSession session) {
    session.setAttribute("sessionMessage", "セッションスコープの値です");
    return "scope";
}

ThymeleafのHTML側では、スコープを明示的に指定して変数を参照します。


<p th:text="${message}">リクエストの値</p>
<p th:text="${session.sessionMessage}">セッションの値</p>

このように、リクエストスコープの変数は${message}で直接参照できますが、セッションスコープの値は${session.xxx}のように「session.」を付けてアクセスします。これを覚えておくと、スコープの違いによる混乱を防げます。

また、アプリケーションスコープを使いたい場合は、ServletContextを通じて値を設定します。全ユーザーに共通する情報を管理したいときに便利です。


@Autowired
private ServletContext context;

@GetMapping("/app-scope")
public String appScope() {
    context.setAttribute("appMessage", "アプリケーション全体の共通メッセージ");
    return "scope";
}


<p th:text="${application.appMessage}">アプリケーション共通メッセージ</p>

このように、Thymeleafではスコープを指定するだけで簡単にアクセスできます。Spring MVCと組み合わせることで、画面間でのデータ共有を柔軟に実現できます。

新人

「セッションに保存した変数は、別のページでも使えるんですね！でも、リクエストスコープの値は毎回消えるんですか？」

先輩

「その通り。リクエストスコープは一時的な通信で使われるものだから、次のリクエストでは初期化されるんだ。必要に応じてセッションスコープを使い分けるのがポイントだね。」

9. よくある間違いと注意点（変数が表示されない・スコープの混同など）

Thymeleafを使う初心者がよくつまずくのが、変数が表示されないという問題です。この原因の多くはスコープの扱い方にあります。例えば、Modelで設定したリクエストスコープの変数を、別ページで${}で参照しようとしても表示されません。これはリクエストが切り替わっているためです。

また、セッションスコープに値を入れたのに表示されない場合は、HTML側で${session.変数名}の形式を忘れているケースが多いです。Thymeleafでは、スコープを明示しないとデフォルトでリクエストスコープが参照される点に注意しましょう。

もう一つの典型的な間違いは、変数名の不一致です。Java側でmodel.addAttribute("userName", "山田太郎");と設定したのに、テンプレート側で${username}のように小文字で書いてしまうと、値は表示されません。変数名は完全一致で参照されるため、大文字小文字も区別されます。

さらに、th:text属性を付け忘れていると、Thymeleafが値を展開しません。単にHTML内に${name}と書いても認識されないので、必ずth:text="${name}"のように書く必要があります。

もし画面に何も表示されない場合は、まず次の点を確認しましょう。