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 13Template inheritance is one of the most powerful features of Twig but it is 14limited to single inheritance; a template can only extend one other template. 15This limitation makes template inheritance simple to understand and easy to 16debug: 17 18.. code-block:: jinja 19 20 {% extends "base.html" %} 21 22 {% block title %}{% endblock %} 23 {% block content %}{% endblock %} 24 25Horizontal reuse is a way to achieve the same goal as multiple inheritance, 26but 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 37The ``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 46In this example, the ``use`` statement imports the ``sidebar`` block into the 47main template. The code is mostly equivalent to the following one (the 48imported 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 69The main template can also override any imported block. If the template 70already defines the ``sidebar`` block, then the one defined in ``blocks.html`` 71is 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 86The ``parent()`` function automatically determines the correct inheritance 87tree, so it can be used when overriding a block defined in an imported 88template: 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 103In this example, ``parent()`` will correctly call the ``sidebar`` block from 104the ``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. 125