vendor/twig/twig/doc/tags/macro.rst

   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>`