]>
Commit | Line | Data |
---|---|---|
4f5b44bd NL |
1 | ``macro`` |
2 | ========= | |
3 | ||
4 | Macros are comparable with functions in regular programming languages. They | |
5 | are useful to put often used HTML idioms into reusable elements to not repeat | |
6 | yourself. | |
7 | ||
8 | Here is a small example of a macro that renders a form element: | |
9 | ||
10 | .. code-block:: jinja | |
11 | ||
12 | {% macro input(name, value, type, size) %} | |
13 | <input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}" /> | |
14 | {% endmacro %} | |
15 | ||
16 | Macros differs from native PHP functions in a few ways: | |
17 | ||
18 | * Default argument values are defined by using the ``default`` filter in the | |
19 | macro body; | |
20 | ||
21 | * Arguments of a macro are always optional. | |
22 | ||
23 | But as with PHP functions, macros don't have access to the current template | |
24 | variables. | |
25 | ||
26 | .. tip:: | |
27 | ||
28 | You can pass the whole context as an argument by using the special | |
29 | ``_context`` variable. | |
30 | ||
31 | Macros can be defined in any template, and need to be "imported" before being | |
32 | used (see the documentation for the :doc:`import<../tags/import>` tag for more | |
33 | information): | |
34 | ||
35 | .. code-block:: jinja | |
36 | ||
37 | {% import "forms.html" as forms %} | |
38 | ||
39 | The above ``import`` call imports the "forms.html" file (which can contain only | |
40 | macros, or a template and some macros), and import the functions as items of | |
41 | the ``forms`` variable. | |
42 | ||
43 | The macro can then be called at will: | |
44 | ||
45 | .. code-block:: jinja | |
46 | ||
47 | <p>{{ forms.input('username') }}</p> | |
48 | <p>{{ forms.input('password', null, 'password') }}</p> | |
49 | ||
50 | If macros are defined and used in the same template, you can use the | |
51 | special ``_self`` variable to import them: | |
52 | ||
53 | .. code-block:: jinja | |
54 | ||
55 | {% import _self as forms %} | |
56 | ||
57 | <p>{{ forms.input('username') }}</p> | |
58 | ||
59 | .. warning:: | |
60 | ||
61 | When you define a macro in the template where you are going to use it, you | |
62 | might be tempted to call the macro directly via ``_self.input()`` instead | |
63 | of importing it; even if seems to work, this is just a side-effect of the | |
64 | current implementation and it won't work anymore in Twig 2.x. | |
65 | ||
66 | When you want to use a macro in another macro from the same file, you need to | |
67 | import it locally: | |
68 | ||
69 | .. code-block:: jinja | |
70 | ||
71 | {% macro input(name, value, type, size) %} | |
72 | <input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}" /> | |
73 | {% endmacro %} | |
74 | ||
75 | {% macro wrapped_input(name, value, type, size) %} | |
76 | {% import _self as forms %} | |
77 | ||
78 | <div class="field"> | |
79 | {{ forms.input(name, value, type, size) }} | |
80 | </div> | |
81 | {% endmacro %} | |
82 | ||
83 | .. seealso:: :doc:`from<../tags/from>`, :doc:`import<../tags/import>` |