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

新人

「Thymeleafで変数を使うとき、どんな特徴がありますか？そしてフラグメントって何ですか？」

先輩

「Thymeleafの変数は、Spring MVCのモデルから渡されてテンプレート内で使われる値だよ。フラグメントはHTMLの共通部分を切り出して、複数のページで再利用できる仕組みなんだ。」

新人

「共通部品としてのフラグメントは、具体的にどうやって使うんでしょう？」

先輩

「それはこれから詳しく説明するよ。まずは変数の基本とフラグメントの概念から理解していこう。」

1. Thymeleafの変数とは？基本的な使い方と特徴

Thymeleafの変数は、Spring MVCのコントローラでモデルにセットしたデータをテンプレート内で参照するためのものです。モデルはリクエストごとに生成され、変数はリクエストスコープで管理されます。

例えば、コントローラで以下のようにモデルに値をセットします。


@Controller
public class SampleController {

    @GetMapping("/hello")
    public String hello(Model model) {
        model.addAttribute("message", "こんにちは、Thymeleaf!");
        return "hello";
    }
}

そしてテンプレート内で変数を参照するには、以下のように記述します。


<p th:text="${message}">ここにメッセージが表示されます</p>

このように、${}で囲んだ名前がモデルの変数名に対応していて、動的に値を表示できます。Thymeleaf変数はデータを画面に渡す基本的な仕組みです。

また、変数はローカルなスコープとしてth:withでテンプレート内に定義も可能で、一時的な値を効率的に管理できます。

2. フラグメントとは何か？共通部品管理の基本概念

フラグメントは、Thymeleafで共通のHTMLパーツを切り出し、複数のテンプレートで再利用できる機能です。例えばヘッダーやフッター、ナビゲーションメニューなどをフラグメント化しておくと、修正や更新が楽になります。

フラグメントは通常、単独のHTMLファイルやテンプレート内の一部として作成します。以下は、フラグメントを定義した例です。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<body>
    <div th:fragment="header">
        <header>
            <h1>サイトのヘッダー</h1>
        </header>
    </div>
</body>
</html>

このth:fragment="header"が付いた部分がフラグメントです。別のテンプレートから以下のように呼び出して使います。


<div th:replace="fragments :: header"></div>

ここでfragmentsはフラグメントを定義したテンプレートのファイル名（拡張子なし）、headerはフラグメント名です。この仕組みで共通部品の管理と再利用ができます。

フラグメントはコードの重複を減らし、保守性を向上させる重要なテクニックです。Spring MVCとPleiades、Gradle環境で効率的に使いこなしましょう。

3. Spring MVCの@Controllerで変数を使ってフラグメントに値を渡す方法

Spring MVCのコントローラでは、モデルに変数をセットし、その値をThymeleafのフラグメントに渡して動的な共通部品を作ることができます。変数を渡すことで、フラグメントの内容を柔軟に変更可能です。

まずは、コントローラでモデルに変数をセットする例を見てみましょう。


@Controller
public class CommonController {

    @GetMapping("/page")
    public String showPage(Model model) {
        model.addAttribute("pageTitle", "ホームページ");
        model.addAttribute("userName", "田中一郎");
        return "page";
    }
}

この例では、pageTitleとuserNameという変数をモデルにセットしています。これらの変数はThymeleafのテンプレートで参照でき、フラグメントにも渡せます。

Thymeleafのフラグメント呼び出しで変数を渡すには、th:with属性を使います。次のセクションで具体的に説明します。

4. フラグメントでの変数の受け取り方と再利用のコツ

フラグメントに変数を渡すときは、th:withを用いて渡したい値を指定します。フラグメント側では、渡された変数を通常のThymeleaf変数として受け取り使うことができます。

例えば、以下のようにフラグメントを定義します。


<div th:fragment="headerFragment(title, user)">
    <header>
        <h1 th:text="${title}">タイトル</h1>
        <p>ようこそ、<span th:text="${user}">ユーザー</span>さん</p>
    </header>
</div>

このフラグメントはtitleとuserという引数を受け取ります。これを呼び出すテンプレートは次のようになります。


<div th:replace="fragments :: headerFragment (~{pageTitle}, ~{userName})"></div>

th:replaceの中で~{変数名}を使って、モデル変数をフラグメントの引数に渡しています。こうすることでフラグメントは動的に表示内容を変えられます。

コツとしては、フラグメントの引数名とコントローラで渡す変数名は違っても問題ありませんが、呼び出し側で正しくマッピングすることが重要です。複数の変数を渡す場合はカンマで区切り、順番に対応させます。

5. 共通部品としてのフラグメントの作成と活用事例

フラグメントは共通部品としてヘッダーやフッター、サイドメニュー、ナビゲーションバーなど様々な箇所で利用可能です。ここでは代表的な例を示します。

たとえば、サイトのヘッダーを共通化したい場合は、fragments.htmlに以下のように定義します。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<body>
    <div th:fragment="header(title)">
        <header>
            <h1 th:text="${title}">サイトタイトル</h1>
            <nav>
                <ul>
                    <li><a href="/" th:href="@{/}">ホーム</a></li>
                    <li><a href="/about" th:href="@{/about}">会社概要</a></li>
                    <li><a href="/contact" th:href="@{/contact}">お問い合わせ</a></li>
                </ul>
            </nav>
        </header>
    </div>
</body>
</html>

そして、ページのテンプレートでは以下のように呼び出します。


<div th:replace="fragments :: header(~{pageTitle})"></div>

このようにpageTitleという変数を渡してヘッダーのタイトルを動的に変えられます。フラグメントの活用で複数ページに共通する部品を簡単に管理でき、メンテナンスも効率的になります。

さらに、フッターやナビゲーションメニュー、サイドバーも同様にフラグメント化して使い回すことで、コードの重複を避けて保守性を高めることができます。

Spring MVCのモデルとThymeleafのフラグメントを連携させることで、柔軟で再利用可能なUI部品の管理が実現できるのです。

6. フラグメントと変数管理でよくあるトラブルとその対処法

Thymeleafのフラグメントと変数管理を使う際によくあるトラブルとその解決方法を知っておくことは、開発の効率化とトラブルシューティングに役立ちます。ここでは代表的な問題と対処法を詳しく説明します。

6-1. 変数がフラグメント内でnullになる問題

Spring MVCのコントローラでモデルに変数をセットしていても、フラグメントでその変数がnullとして扱われることがあります。これは主に、変数の渡し方やスコープの誤りが原因です。

例えば、フラグメントを呼び出す際にth:withで変数を正しく渡していない場合、フラグメント内で変数が参照できません。


<!-- NG例：変数を渡していない -->
<div th:replace="fragments :: headerFragment"></div>

このように呼び出すと、headerFragment内で期待する変数が見つからずnullになります。正しくは以下のように変数を渡しましょう。


<div th:replace="fragments :: headerFragment (~{pageTitle}, ~{userName})"></div>

変数名のタイプミスにも注意が必要です。コントローラのモデル名とテンプレート側の変数名は必ず一致させましょう。

6-2. 変数名の競合による表示エラー

フラグメント内でローカル変数を定義するとき、モデルの変数名と同じ名前を使うと競合が起き、意図しない表示になることがあります。これは、ローカル変数が優先されるためです。

例えば、フラグメント内でuserNameという変数をローカルに定義すると、モデルのuserNameは隠されます。こうした競合を避けるため、ローカル変数には別の名前を使うか、必要な場合は明示的に参照を分けましょう。

6-3. フラグメント呼び出し時のパス間違い

フラグメントを呼び出す際に、テンプレートファイル名やパスを間違えるケースも多いです。特にPleiades環境でGradleを使う場合、リソースの場所に注意し、正しいパスを指定しましょう。

ファイル名やフラグメント名を変更した場合は、必ず呼び出し先も修正してください。パスや名前が合っていないと、呼び出し時にエラーが発生し、画面が表示されません。

7. 効率的な共通部品管理のためのベストプラクティス

Thymeleafのフラグメントと変数を活用して効率的に共通部品を管理するためのポイントを紹介します。これらのベストプラクティスは開発効率と保守性の向上に直結します。

7-1. フラグメントは役割ごとに分割する

ヘッダー、フッター、ナビゲーションなど共通部品はそれぞれ独立したフラグメントとして分割しましょう。こうすることで修正時の影響範囲が限定され、バグの混入を防ぎやすくなります。

7-2. 変数の命名規則を統一する

モデル変数やフラグメント引数の名前はプロジェクト全体で統一しましょう。命名規則がばらばらだと混乱や誤用が増えます。チーム内で命名ルールを決めて、コードレビューでチェックするのがおすすめです。

7-3. 変数のスコープを意識して管理する

モデル変数は基本的にリクエストスコープですが、ユーザー情報など複数画面で使うデータはセッションスコープに置くことも検討してください。@SessionAttributesの活用も有効です。

7-4. フラグメントの引数は必要最小限にする

フラグメントに渡す引数はできるだけ必要最低限に絞りましょう。多くの引数を渡すと呼び出しが複雑になり、管理が難しくなります。必要に応じて、モデルオブジェクトをまとめて渡す方法も検討してください。

7-5. 共有フラグメントは専用ディレクトリにまとめる

共通のフラグメントはプロジェクト内で分かりやすい場所にまとめ、管理しやすくしましょう。例えばtemplates/fragments/ディレクトリに集約するのが一般的です。

8. まとめと今後の学習に役立つアドバイス

Thymeleafの変数とフラグメントを活用した共通部品管理は、Spring MVCを使ったウェブ開発において非常に重要な技術です。これにより、画面のコードがシンプルになり、保守や拡張が楽になります。

今回の記事では、変数の基本的な使い方、フラグメントの定義と呼び出し、変数の渡し方やよくあるトラブルとその解決方法、さらに効率的な管理のためのベストプラクティスまでを詳しく解説しました。

今後は以下のポイントを意識して学習を進めると良いでしょう。

Spring MVCのモデルとThymeleaf変数の関係を深く理解する
フラグメントの引数渡しや動的パラメータの扱いに慣れる
共通部品の設計と保守性を考えたテンプレート構成を工夫する
実際のプロジェクトで積極的にフラグメントを使い、経験を積む

また、Spring BootやThymeleafの公式ドキュメント、書籍、オンラインチュートリアルを活用して理解を深めていくこともおすすめします。

Thymeleafの変数操作やフラグメント管理のスキルは、ウェブ開発の現場で非常に役立つので、しっかり習得していきましょう。

Thymeleaf 変数とフラグメントで共通部品を管理｜初心者向けSpring MVC × Pleiades × Gradle解説