1``macro``
2=========
3
4Macros are comparable with functions in regular programming languages. They
5are useful to reuse template fragments to not repeat yourself.
6
7Macros are defined in regular templates.
8
9Imagine having a generic helper template that define how to render HTML forms
10via macros (called ``forms.html``):
11
12.. code-block:: html+twig
13
14    {% macro input(name, value, type = "text", size = 20) %}
15        <input type="{{ type }}" name="{{ name }}" value="{{ value|e }}" size="{{ size }}"/>
16    {% endmacro %}
17
18    {% macro textarea(name, value, rows = 10, cols = 40) %}
19        <textarea name="{{ name }}" rows="{{ rows }}" cols="{{ cols }}">{{ value|e }}</textarea>
20    {% endmacro %}
21
22Each macro argument can have a default value (here ``text`` is the default value
23for ``type`` if not provided in the call).
24
25Macros differ from native PHP functions in a few ways:
26
27* Arguments of a macro are always optional.
28
29* If extra positional arguments are passed to a macro, they end up in the
30  special ``varargs`` variable as a list of values.
31
32But as with PHP functions, macros don't have access to the current template
33variables.
34
35.. tip::
36
37    You can pass the whole context as an argument by using the special
38    ``_context`` variable.
39
40Importing Macros
41----------------
42
43There are two ways to import macros. You can import the complete template
44containing the macros into a local variable (via the ``import`` tag) or only
45import specific macros from the template (via the ``from`` tag).
46
47To import all macros from a template into a local variable, use the ``import``
48tag:
49
50.. code-block:: twig
51
52    {% import "forms.html" as forms %}
53
54The above ``import`` call imports the ``forms.html`` file (which can contain
55only macros, or a template and some macros), and import the macros as items of
56the ``forms`` local variable.
57
58The macros can then be called at will in the *current* template:
59
60.. code-block:: html+twig
61
62    <p>{{ forms.input('username') }}</p>
63    <p>{{ forms.input('password', null, 'password') }}</p>
64
65Alternatively you can import names from the template into the current namespace
66via the ``from`` tag:
67
68.. code-block:: html+twig
69
70    {% from 'forms.html' import input as input_field, textarea %}
71
72    <p>{{ input_field('password', '', 'password') }}</p>
73    <p>{{ textarea('comment') }}</p>
74
75.. tip::
76
77    When macro usages and definitions are in the same template, you don't need to
78    import the macros as they are automatically available under the special
79    ``_self`` variable:
80
81    .. code-block:: html+twig
82
83        <p>{{ _self.input('password', '', 'password') }}</p>
84
85        {% macro input(name, value, type = "text", size = 20) %}
86            <input type="{{ type }}" name="{{ name }}" value="{{ value|e }}" size="{{ size }}"/>
87        {% endmacro %}
88
89    Auto-import is only available as of Twig 2.11. For older versions, import
90    macros using the special ``_self`` variable for the template name:
91
92    .. code-block:: html+twig
93
94        {% import _self as forms %}
95
96        <p>{{ forms.input('username') }}</p>
97
98.. note::
99
100    Before Twig 2.11, when you want to use a macro in another macro from the
101    same file, you need to import it locally:
102
103    .. code-block:: html+twig
104
105        {% macro input(name, value, type, size) %}
106            <input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}"/>
107        {% endmacro %}
108
109        {% macro wrapped_input(name, value, type, size) %}
110            {% import _self as forms %}
111
112            <div class="field">
113                {{ forms.input(name, value, type, size) }}
114            </div>
115        {% endmacro %}
116
117Macros Scoping
118--------------
119
120.. versionadded:: 2.11
121
122    The scoping rules described in this paragraph are implemented as of Twig
123    2.11.
124
125The scoping rules are the same whether you imported macros via ``import`` or
126``from``.
127
128Imported macros are always **local** to the current template. It means that
129macros are available in all blocks and other macros defined in the current
130template, but they are not available in included templates or child templates;
131you need to explicitly re-import macros in each template.
132
133Imported macros are not available in the body of ``embed`` tags, you need
134to explicitly re-import macros inside the tag.
135
136When calling ``import`` or ``from`` from a ``block`` tag, the imported macros
137are only defined in the current block and they override macros defined at the
138template level with the same names.
139
140When calling ``import`` or ``from`` from a ``macro`` tag, the imported macros
141are only defined in the current macro and they override macros defined at the
142template level with the same names.
143
144.. note::
145
146    Before Twig 2.11, it was possible to use macros imported in a block in a
147    "sub-block". When upgrading to 2.11, you need to either move the import in
148    the global scope or reimport the macros explicitly in the "sub-blocks".
149
150Checking if a Macro is defined
151------------------------------
152
153.. versionadded:: 2.11
154
155    Support for the ``defined`` test on macros was added in Twig 2.11.
156
157You can check if a macro is defined via the ``defined`` test:
158
159.. code-block:: twig
160
161    {% import "macros.twig" as macros %}
162
163    {% from "macros.twig" import hello %}
164
165    {% if macros.hello is defined -%}
166        OK
167    {% endif %}
168
169    {% if hello is defined -%}
170        OK
171    {% endif %}
172
173Named Macro End-Tags
174--------------------
175
176Twig allows you to put the name of the macro after the end tag for better
177readability (the name after the ``endmacro`` word must match the macro name):
178
179.. code-block:: twig
180
181    {% macro input() %}
182        ...
183    {% endmacro input %}
184