【Flask】WTFormsのテンプレートマクロの基本と実践方法｜Chapter4-6

一つ前のページではカスタムバリデータについて学習しました。

今回は テンプレートマクロ について見ていきましょう。

Flaskでアプリケーションを作っていると、HTMLテンプレートの中で同じようなコードを何度も書くことが出てきます。

たとえばフォームの入力欄やボタンなど、見た目や処理が似たような部分が増えるとどんどんテンプレートが長くなり、管理が大変になります。

そんなときに役立つのが「テンプレートマクロ」です。

マクロを使えば共通パターンをテンプレートの中に一つの「部品」として定義しておくことができ、それを繰り返し使い回すことができます。

これによりテンプレートがすっきりし、保守性も高まります。

<<前のページ

Flaskの記事一覧

次のページ>>

テンプレートマクロの基本構文と書き方

「マクロ（macro）」という言葉には「何かを簡略化してくれる仕組み」といった意味があります。

Flaskで使われるJinja2テンプレートでもこの「マクロ」を使うことができます。

そしてテンプレートマクロとは、HTML内で何度も使いたいコードのパターンを「Pythonの関数のように」定義し、必要な場所で呼び出すための仕組みです。

特にフォームのフィールド表示など、複雑で繰り返しがちな部分に活用すると非常に便利です。

テンプレートマクロの定義と呼出し

テンプレートマクロを定義するには以下のような構文を使います。

<!-- 新規マクロの定義 -->
{% macro マクロ名(引数1, 引数2, ...) %}
    <!-- マクロの中身（HTMLコードなど） -->
{% endmacro %}

そして定義したマクロは次のようにして呼び出します。

<!-- 定義されたマクロの呼び出し -->
{{ マクロ名(引数1, 引数2, ...) }}

例えば、名前を表示するだけの簡単なマクロを作ってみましょう。

<!-- テンプレートマクロhello()の定義 -->
{% macro hello(name) %}
  <p>こんにちは、{{ name }}さん！</p>
{% endmacro %}

<!-- hello()マクロの呼び出し -->
{{ hello("佐藤") }}

このよう「同じようなコード」を部品として定義しておけば、テンプレート内の記述を短く、そして柔軟に保つことができます。

フォームUIを簡略化するテンプレートマクロの実用例

では実際にマクロがどのように使えるのか、フォーム入力欄を例に見てみましょう。

以下のマクロは、Webフォームを

• ラベル
• 入力欄
• エラーメッセージ（エラーがある場合）

の３つの構成で見やすく、簡単に表示するための再利用テンプレート部品です。

<!-- render_fieldという名前のテンプレートマクロの定義 -->
{% macro render_field(field, label_text) %} <!-- 2つの引数を持つテンプレートマクロの定義 -->

  <div class="form-group">
    <label>{{ label_text }}</label>	  <!-- 変数label_textをラベル表示 -->
    
    {{ field(class="form-control") }} <!-- 入力欄（フィールドオブジェクト） -->
    
    {% if field.errors %}  <!-- バリデーション（もしエラーがあるなら） -->
      <ul class="error-list">
        {% for error in field.errors %}
          <li>{{ error }}</li>
        {% endfor %}
      </ul>
    {% endif %}
  </div>

{% endmacro %} <!-- ここまでがテンプレートマクロ -->

他のテンプレートから呼び出す場合は以下のように書きます。

<!-- macro.htmlで定義されたrender_fieldというマクロを使用する宣言 -->
{% from "_macro.html" import render_field %}

<form method="POST">
  <!-- render_fieldマクロの呼び出し -->
  {{ render_field(form.username, "ユーザー名") }}
  {{ render_field(form.password, "パスワード") }}
  <!-- 送信ボタン -->
  {{ form.submit() }}
</form>

これによって複数の入力フィールドを同じ見た目・同じ構造で記述することができ、コードの見通しがとても良くなります。

あわせて読みたい

【Python】レッスン3-1：関数の基本を理解しよう

マクロ利用時の注意点とおすすめの使い方

マクロは便利ですが、使いすぎるとコードが分かりづらくなることもあります。
以下の点に注意しましょう。

まとめ｜マクロでテンプレート開発を効率化しよう

今回はFlaskにおけるテンプレートマクロの基本について学びました。

テンプレートマクロを活用すれば、HTMLコードの再利用性が高まり、見通しも良くなります。

少し難しく感じるかもしれませんが、使い方に慣れればとても強力な武器になります。

自分だけの「便利テンプレート集」を作って、どんどん開発を効率化していきましょう！

練習問題：テンプレートマクロで再利用可能なボタンUIを作成しよう

この問題では、Jinja2テンプレートマクロを使って2種類のボタン（「送信」「キャンセル」）を表示するコードを作成します。

アプリファイルは下記の物を使用し、テンプレートファイル（HTMLファイル）を2つ作成してください。

この練習を通じて、マクロの定義方法やマクロを他のテンプレートで使う方法を学びましょう。

from flask import Flask, render_template

app = Flask(__name__)

@app.route("/")
def index():
    return render_template("index.html")

if __name__ == "__main__":
    app.run(debug=True)

この問題の要件

以下の要件に従って「templates/_macro.html」を完成させてください。

以下の要件に従って「templates/index.html」を完成させてください。

この問題を解くヒント

１からコードを組み立てることが難しい場合は、以下のヒントを開いて参考にしましょう。

このヒントを見てもまだ回答を導き出すのが難しいと感じる場合は、先に正解のコードと解説を見て内容を理解するようにしましょう。

正解コード

例えば、以下のようなプログラムが考えられます。

正解コードの詳細解説

正解コードをブロックごとに分割して解説します。

<<前のページ

Flaskの記事一覧

次のページ>>

FAQ｜テンプレートマクロの使い方と活用方法