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

新人

「Thymeleaf layoutって何ですか？共通レイアウトを使いたいんですけど…」

先輩

「Thymeleaf layoutは、ヘッダーやフッターなど共通部分をテンプレート化して、効率的に再利用する仕組みだよ。」

新人

「再利用って具体的にはどうやって？」

先輩

「まず、共通レイアウトのテンプレートを作って、各ページはそこに内容だけ差し込むようにするんだ。実際に見てみよう！」

1. Thymeleaf layoutとは？

Thymeleaf layoutとは、Webページで共通のヘッダー、ナビゲーション、フッターなどをテンプレートとしてまとめておき、個別のページから必要な部分だけを差し込む仕組みです。テンプレートエンジンThymeleafを使えば、再利用性の高いコードが書け、保守性や開発効率も向上します。

開発環境はPleiadesで、Gradleプロジェクトとして作成します。コントローラは@Controllerを使い、MavenではなくGradleで依存関係もPleiadesのチェックで追加します。

2. layoutを使うメリット

共通レイアウトを導入することで、主に次のようなメリットがあります。

2-1. 共通化による開発効率の向上

ヘッダーやフッターを各ページでコピーせず、1つのテンプレートにまとめることで、変更があっても一箇所変更すれば済みます。開発の手間が減り、作業ミスの可能性も低くなります。

2-2. 保守性の向上

共通部分をテンプレート化して分離することで、HTML構造が見やすくなり、保守作業が楽になります。例えばサイトデザインのヘッダーが変わったときに、簡単に更新できます。

2-3. コードの見通しがよくなる

各ページに表示するコンテンツだけを記述すればよくなり、テンプレートがすっきり整理されます。初心者でもHTML構造を理解しやすくなります。

次のセクションでは、共通レイアウトの実装例を見ていきましょう！

3. layoutを使う際の基本構造と仕組み

Thymeleaf layoutでは、共通テンプレート（layout）と差し込むコンテンツ部分を分けて管理します。共通テンプレートに「ここに内容を入れるよ」と指定しておき、実際のページからその場所に中身を差し込む仕組みです。

3-1. layoutテンプレートの基本構造

共通layout.htmlには、ヘッダーやナビゲーション、フッターを記述しておき、差し込み部分にはth:insertやth:replaceでマークしておきます。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
  <title>共通レイアウト</title>
</head>
<body>
  <header>
    <h1>サイト共通ヘッダー</h1>
  </header>
  <div th:insert="~{::main}">コンテンツが入ります</div>
  <footer>
    <p>サイト共通フッター</p>
  </footer>
</body>
</html>

3-2. ページ側テンプレートの仕組み

個別ページでは、layout:decorate属性で共通テンプレートを指定し、差し込みたい部分をth:fragmentで定義します。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org"
      layout:decorate="~{layout}">
  <div th:fragment="main">
    <p>このページの内容</p>
  </div>
</html>

これにより、layout.htmlのth:insert部分に、ページのmainフラグメントが差し込まれます。

4. layoutの使い方の例（具体的なテンプレート例）

ここでは、PleiadesのGradleプロジェクトで構築するSpring Boot＋Thymeleafでの具体例を紹介します。

4-1. 共通テンプレート（layout.html）


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
  <meta charset="UTF-8">
  <title th:text="${pageTitle}">タイトル</title>
</head>
<body>
  <header th:fragment="header">
    <nav>ナビゲーションリンク</nav>
  </header>
  <main th:fragment="content">
    <!-- 各ページの内容 -->
  </main>
  <footer th:fragment="footer">
    <p>&copy; 2025 サイト名</p>
  </footer>
</body>
</html>

4-2. 個別ページテンプレート（home.html）


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org"
      layout:decorate="~{layout}">
  <div th:fragment="content">
    <h2>ホームページ</h2>
    <p>ここがメインコンテンツです。</p>
  </div>
</html>

4-3. コントローラ側の設定例


@Controller
public class HomeController {
    @GetMapping("/")
    public String home(Model model) {
        model.addAttribute("pageTitle", "ホーム");
        return "home";
    }
}

この設定で、タイトルも動的に差し込まれ、共通ヘッダー・フッター付きのページが表示できます。

5. layoutでよく使うタグや属性の使い方

layout実装においてよく使うタグや属性について初心者向けに整理します。

5-1. layout:decorate

個別ページで共通layoutを指定する属性。必須項目です。例：


<html layout:decorate="~{layout}">

5-2. th:fragment

共通テンプレートや個別テンプレートで差し込み可能なパーツを定義するために使います。名前を一致させることで差し込みが可能になります。


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

5-3. th:insert / th:replace

共通テンプレート内で、個別ページのフラグメントを移し替えるために使います。insertは内容をそのまま差し込み、replaceはタグごと置き換えます。


<div th:insert="~{::content}"></div>
<!-- または -->
<div th:replace="~{::content}"></div>

5-4. デザイン調整のための属性

必要に応じて、ヘッダー内のリンクやCSSパスを個別ページから動的に渡したい場合、th:textやth:hrefを使って実装します。


<link rel="stylesheet" th:href="@{/css/main.css}" />
<a th:href="@{/home}" th:text="${homeLink}">ホームへ</a>

6. layoutを使うときの注意点

共通レイアウトを利用する際に起こりやすいトラブルや注意すべきポイントを初心者向けに整理します。

6-1. Thymeleafバージョンによる仕様差

Thymeleafのバージョンによって、layout:decorateやth:insertの扱いが微妙に変わることがあります。特に3.0と3.1で互換性が違う場合があるため、Pleiadesでエラーが出たらThymeleafバージョンを確認しましょう。

6-2. namespace宣言の忘れに注意

layoutを使うときはHTMLのルート要素にxmlns:layout宣言が必要です。例えば:


<html xmlns:th="http://www.thymeleaf.org"
      xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout">

この宣言を忘れると、layout:decorateなどの属性が動作せずエラーになります。

6-3. template resolver設定

PleiadesのGradleプロジェクトでは、spring.thymeleaf.prefixやsuffixでテンプレートの場所と拡張子を正しく設定する必要があります。誤ったパスだと共通レイアウトが読み込まれず403や404になる可能性があります。

6-4. fragment名の重複に注意

共通テンプレートと個別ページで同じフラグメント名を使うと競合する場合があります。名前はわかりやすく命名しておくのがおすすめです。

7. これからThymeleaf layoutを学ぶためのおすすめの方法

Thymeleaf layoutに慣れるために効果的な学習方法を初心者向けにご紹介します。

7-1. 公式ドキュメントを読む

まずはThymeleafの公式サイトでlayoutダイアレクトの使い方を確認しましょう。基本的なlayout:decorateやth:fragmentなどの使い方を実例で理解できます。

7-2. Pleiadesで小さなサンプルを作成

PleiadesのGradleプロジェクトで「ヘッダー・フッター・サイドバー」を持つ小さなサイトを作ってみましょう。共通layoutとページを分けて実装し、画面遷移を確認することで実用的な理解が進みます。

7-3. 実践でfragmentをカスタマイズ

慣れてきたら共通テンプレートに可変部分（例：ページタイトルやCSSリンク）を追加してみましょう。モデルからModelで渡す値を使って動的に変更できるようになります。

7-4. トラブルが起きたらネット検索

エラーメッセージをそのままGoogle検索すると、StackOverflowやQiitaなどで解決例が見つかることが多いです。Pleiadesでの環境設定エラーも、解決策がすぐ見つかります。

8. layoutを使った具体的なサンプルの例とまとめ

最後に、これまでの内容を踏まえた具体的なサンプルを通して整理します。

8-1. 共通layout（layout.html）


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org"
      xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout">
<head>
  <meta charset="UTF-8">
  <title th:text="${pageTitle}">サイト</title>
</head>
<body>
  <header th:fragment="header">
    <h1>共通ヘッダー</h1>
  </header>
  <main th:insert="~{::content}">
    <!-- ページごとの内容 -->
  </main>
  <footer th:fragment="footer">
    <p>&copy; 2025 サイト名</p>
  </footer>
</body>
</html>

8-2. ホームページ（home.html）


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org"
      xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout"
      layout:decorate="~{layout}">
  <section th:fragment="content">
    <h2>ようこそ！</h2>
    <p>これはホームページのコンテンツです。</p>
  </section>
</html>

8-3. コントローラ（HomeController.java）


@Controller
public class HomeController {
    @GetMapping("/")
    public String home(Model model) {
        model.addAttribute("pageTitle", "ホーム");
        return "home";
    }
}

この構成で、ページタイトル、ヘッダー、フッターは共通化され、ページごとのコンテンツだけを記述できます。Pleiades+Gradleの開発環境でもこの仕組みはすぐに応用でき、初心者でも実装に慣れやすい構成です。

共通レイアウトを使うことで、コードが整理され、再利用性や保守性が高まり、開発効率も向上します。この記事で紹介したポイントを参考に、自分だけの共通レイアウトを作ってみてください！