www.aleph1.co.uk Git - yaffs-website/blob - 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 differ 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 * If extra positional arguments are passed to a macro, they end up in the
  24   special ``varargs`` variable as a list of values.
  25
  26 But as with PHP functions, macros don't have access to the current template
  27 variables.
  28
  29 .. tip::
  30
  31     You can pass the whole context as an argument by using the special
  32     ``_context`` variable.
  33
  34 Import
  35 ------
  36
  37 Macros can be defined in any template, and need to be "imported" before being
  38 used (see the documentation for the :doc:`import<../tags/import>` tag for more
  39 information):
  40
  41 .. code-block:: jinja
  42
  43     {% import "forms.html" as forms %}
  44
  45 The above ``import`` call imports the "forms.html" file (which can contain only
  46 macros, or a template and some macros), and import the functions as items of
  47 the ``forms`` variable.
  48
  49 The macro can then be called at will:
  50
  51 .. code-block:: jinja
  52
  53     <p>{{ forms.input('username') }}</p>
  54     <p>{{ forms.input('password', null, 'password') }}</p>
  55
  56 If macros are defined and used in the same template, you can use the
  57 special ``_self`` variable to import them:
  58
  59 .. code-block:: jinja
  60
  61     {% import _self as forms %}
  62
  63     <p>{{ forms.input('username') }}</p>
  64
  65 .. warning::
  66
  67     When you define a macro in the template where you are going to use it, you
  68     might be tempted to call the macro directly via ``_self.input()`` instead
  69     of importing it; even if seems to work, this is just a side-effect of the
  70     current implementation and it won't work anymore in Twig 2.x.
  71
  72 When you want to use a macro in another macro from the same file, you need to
  73 import it locally:
  74
  75 .. code-block:: jinja
  76
  77     {% macro input(name, value, type, size) %}
  78         <input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}" />
  79     {% endmacro %}
  80
  81     {% macro wrapped_input(name, value, type, size) %}
  82         {% import _self as forms %}
  83
  84         <div class="field">
  85             {{ forms.input(name, value, type, size) }}
  86         </div>
  87     {% endmacro %}
  88
  89 Named Macro End-Tags
  90 --------------------
  91
  92 Twig allows you to put the name of the macro after the end tag for better
  93 readability:
  94
  95 .. code-block:: jinja
  96
  97     {% macro input() %}
  98         ...
  99     {% endmacro input %}
 100
 101 Of course, the name after the ``endmacro`` word must match the macro name.
 102
 103 .. seealso:: :doc:`from<../tags/from>`, :doc:`import<../tags/import>`