1``macro``
2=========
3
4.. versionadded:: 1.12
5
6    The possibility to define default values for arguments in the macro
7    signature was added in Twig 1.12.
8
9Macros are comparable with functions in regular programming languages. They
10are useful to put often used HTML idioms into reusable elements to not repeat
11yourself.
12
13Here is a small example of a macro that renders a form element:
14
15.. code-block:: jinja
16
17    {% macro input(name, value, type = "text", size = 20) %}
18        <input type="{{ type }}" name="{{ name }}" value="{{ value|e }}" size="{{ size }}" />
19    {% endmacro %}
20
21Each argument can have a default value (here ``text`` is the default value for
22``type`` if not provided in the call).
23
24.. note::
25
26    Before Twig 1.12, defining default argument values was done via the
27    ``default`` filter in the macro body:
28
29    .. code-block:: jinja
30
31        {% macro input(name, value, type, size) %}
32            <input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}" />
33        {% endmacro %}
34
35Macros differ from native PHP functions in a few ways:
36
37* Arguments of a macro are always optional.
38
39* If extra positional arguments are passed to a macro, they end up in the
40  special ``varargs`` variable as a list of values.
41
42But as with PHP functions, macros don't have access to the current template
43variables.
44
45.. tip::
46
47    You can pass the whole context as an argument by using the special
48    ``_context`` variable.
49
50Import
51------
52
53Macros can be defined in any template, and need to be "imported" before being
54used (see the documentation for the :doc:`import<../tags/import>` tag for more
55information):
56
57.. code-block:: jinja
58
59    {% import "forms.html" as forms %}
60
61The above ``import`` call imports the "forms.html" file (which can contain only
62macros, or a template and some macros), and import the functions as items of
63the ``forms`` variable.
64
65The macro can then be called at will:
66
67.. code-block:: jinja
68
69    <p>{{ forms.input('username') }}</p>
70    <p>{{ forms.input('password', null, 'password') }}</p>
71
72If macros are defined and used in the same template, you can use the
73special ``_self`` variable to import them:
74
75.. code-block:: jinja
76
77    {% import _self as forms %}
78
79    <p>{{ forms.input('username') }}</p>
80
81.. warning::
82
83    When you define a macro in the template where you are going to use it, you
84    might be tempted to call the macro directly via ``_self.input()`` instead
85    of importing it; even if seems to work, this is just a side-effect of the
86    current implementation and it won't work anymore in Twig 2.x.
87
88When you want to use a macro in another macro from the same file, you need to
89import it locally:
90
91.. code-block:: jinja
92
93    {% macro input(name, value, type, size) %}
94        <input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}" />
95    {% endmacro %}
96
97    {% macro wrapped_input(name, value, type, size) %}
98        {% import _self as forms %}
99
100        <div class="field">
101            {{ forms.input(name, value, type, size) }}
102        </div>
103    {% endmacro %}
104
105Named Macro End-Tags
106--------------------
107
108Twig allows you to put the name of the macro after the end tag for better
109readability:
110
111.. code-block:: jinja
112
113    {% macro input() %}
114        ...
115    {% endmacro input %}
116
117Of course, the name after the ``endmacro`` word must match the macro name.
118
119.. seealso:: :doc:`from<../tags/from>`, :doc:`import<../tags/import>`
120