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 %}
PHP等のプログラム言語と同様に引数を渡すことが可能です。
また、=で値をあらかじめ入力することで、初期値(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の引数に値を渡しています。
他は設定した初期値が使用されています。
_selfではなくて、別の名前を付けることも可能です。
// 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にありました。
これと同じくらいブログでまとめられたらと思います。