www.aleph1.co.uk Git - yaffs-website/blob - vendor/twig/twig/doc/tags/use.rst

   1 ``use``
   2 =======
   3
   4 .. versionadded:: 1.1
   5     Horizontal reuse was added in Twig 1.1.
   6
   7 .. note::
   8
   9     Horizontal reuse is an advanced Twig feature that is hardly ever needed in
  10     regular templates. It is mainly used by projects that need to make
  11     template blocks reusable without using inheritance.
  12
  13 Template inheritance is one of the most powerful features of Twig but it is
  14 limited to single inheritance; a template can only extend one other template.
  15 This limitation makes template inheritance simple to understand and easy to
  16 debug:
  17
  18 .. code-block:: jinja
  19
  20     {% extends "base.html" %}
  21
  22     {% block title %}{% endblock %}
  23     {% block content %}{% endblock %}
  24
  25 Horizontal reuse is a way to achieve the same goal as multiple inheritance,
  26 but without the associated complexity:
  27
  28 .. code-block:: jinja
  29
  30     {% extends "base.html" %}
  31
  32     {% use "blocks.html" %}
  33
  34     {% block title %}{% endblock %}
  35     {% block content %}{% endblock %}
  36
  37 The ``use`` statement tells Twig to import the blocks defined in
  38 ``blocks.html`` into the current template (it's like macros, but for blocks):
  39
  40 .. code-block:: jinja
  41
  42     {# blocks.html #}
  43
  44     {% block sidebar %}{% endblock %}
  45
  46 In this example, the ``use`` statement imports the ``sidebar`` block into the
  47 main template. The code is mostly equivalent to the following one (the
  48 imported blocks are not outputted automatically):
  49
  50 .. code-block:: jinja
  51
  52     {% extends "base.html" %}
  53
  54     {% block sidebar %}{% endblock %}
  55     {% block title %}{% endblock %}
  56     {% block content %}{% endblock %}
  57
  58 .. note::
  59
  60     The ``use`` tag only imports a template if it does not extend another
  61     template, if it does not define macros, and if the body is empty. But it
  62     can *use* other templates.
  63
  64 .. note::
  65
  66     Because ``use`` statements are resolved independently of the context
  67     passed to the template, the template reference cannot be an expression.
  68
  69 The main template can also override any imported block. If the template
  70 already defines the ``sidebar`` block, then the one defined in ``blocks.html``
  71 is ignored. To avoid name conflicts, you can rename imported blocks:
  72
  73 .. code-block:: jinja
  74
  75     {% extends "base.html" %}
  76
  77     {% use "blocks.html" with sidebar as base_sidebar, title as base_title %}
  78
  79     {% block sidebar %}{% endblock %}
  80     {% block title %}{% endblock %}
  81     {% block content %}{% endblock %}
  82
  83 .. versionadded:: 1.3
  84     The ``parent()`` support was added in Twig 1.3.
  85
  86 The ``parent()`` function automatically determines the correct inheritance
  87 tree, so it can be used when overriding a block defined in an imported
  88 template:
  89
  90 .. code-block:: jinja
  91
  92     {% extends "base.html" %}
  93
  94     {% use "blocks.html" %}
  95
  96     {% block sidebar %}
  97         {{ parent() }}
  98     {% endblock %}
  99
 100     {% block title %}{% endblock %}
 101     {% block content %}{% endblock %}
 102
 103 In this example, ``parent()`` will correctly call the ``sidebar`` block from
 104 the ``blocks.html`` template.
 105
 106 .. tip::
 107
 108     In Twig 1.2, renaming allows you to simulate inheritance by calling the
 109     "parent" block:
 110
 111     .. code-block:: jinja
 112
 113         {% extends "base.html" %}
 114
 115         {% use "blocks.html" with sidebar as parent_sidebar %}
 116
 117         {% block sidebar %}
 118             {{ block('parent_sidebar') }}
 119         {% endblock %}
 120
 121 .. note::
 122
 123     You can use as many ``use`` statements as you want in any given template.
 124     If two imported templates define the same block, the latest one wins.