[Twig]マクロ(macro)の使い方と使用例

Twigのタグ、マクロは、通常のプログラミング言語の関数にあたります。 繰り返し使用されるHTMLの構文などを再利用可能な要素にすることが可能です。

簡単に説明すると、繰り返し使うボタンなどのhtmlを、テンプレート化できるという感じでしょうか。

Official: macro - Documentation

マクロ(macro)の書き方

{% macro basic_button(url, label, marginClass = "mb-3", width = 200) %}
    <a href="{{ url }}" class="btn btn-primary {{ marginClass }}" style="width: {{ width }}px;">
        {{ label }}
    </a>
{% endmacro %}

また、=で値をあらかじめ入力することで、初期値(default)を設定することも可能です。

設定した引数を、通常のTwigの変数と同様に、マクロ内で変数として使用できます。

逆に、引数として設定していない、呼び出し元などの変数はマクロ内では使用できません。

マクロの呼び出し方・使い方

実際に作ったマクロの呼び出し方です。同じTwigファイル内で設定しする以外にも、外部ファイルにマクロのみ設定することも可能です。

同Twig内にあるマクロの呼び出し方

{{ _self.basic_button('/homepage', 'test button') }}

// result
<a href="/homepage" class="btn btn-primary mb-3" style="width: 200;"> test button </a>

同ファイル内にあるマクロは_selfを使うことでアクセス可能です。

上記例だと、最初に作成したbasic_buttonという名前のマクロを呼び出しています。urlとlabelの引数に値を渡しています。

// define _self as button
{% import _self as button %}

// call macro
{{ button.basic_button('/homepage', 'test button', 'mb-5', 300) }}

外部ファイルのマクロの呼び出し方 (import)

上部で作成したマクロが、button_macro.twigというファイル内で定義されていた場合

{% import "button_macro.twig" as button %}

// call macro
{{ button.basic_button('/homepage', 'test button', 'mb-5', 300) }}

外部ファイルとして作成してあるほうが、マクロ自体を他のTwigでも使いまわしできて便利ですね。

外部ファイルのマクロの呼び出し方 (from)

マクロ自体をそのまま、もしくは新たに名前を付けて呼び出すことも可能です。

{% from 'button_macro.html' import basic_button as basic %}

// call macro
{{ basic('/homepage', 'test button', 'mb-5', 300) }}

上記サンプルでは、basic_buttonというマクロに対して、basicと改めて名前を付けて呼び出しています。

includeと違い簡単なパーツ作るイメージで作成できるのが良いと思います。includeだとまとめて読み込むことができませんが、macroは1ファイルにまとめて置けば、複数のマクロを同時にTwig内に読み込むことが可能です。コーディングも楽になると思いますので是非お試しください。

Twigおすすめの書籍

Twigだけに特化した書籍は読んだことがないのですが、AmazonのKindleにありました。