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