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