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