``use``
=======

.. note::

    Horizontal reuse is an advanced Twig feature that is hardly ever needed in
    regular templates. It is mainly used by projects that need to make
    template blocks reusable without using inheritance.

Template inheritance is one of the most powerful features of Twig but it is
limited to single inheritance; a template can only extend one other template.
This limitation makes template inheritance simple to understand and easy to
debug:

.. code-block:: twig

    {% extends "base.html" %}

    {% block title %}{% endblock %}
    {% block content %}{% endblock %}

Horizontal reuse is a way to achieve the same goal as multiple inheritance,
but without the associated complexity:

.. code-block:: twig

    {% extends "base.html" %}

    {% use "blocks.html" %}

    {% block title %}{% endblock %}
    {% block content %}{% endblock %}

The ``use`` statement tells Twig to import the blocks defined in
``blocks.html`` into the current template (it's like macros, but for blocks):

.. code-block:: twig

    {# blocks.html #}
    
    {% block sidebar %}{% endblock %}

In this example, the ``use`` statement imports the ``sidebar`` block into the
main template. The code is mostly equivalent to the following one (the
imported blocks are not outputted automatically):

.. code-block:: twig

    {% extends "base.html" %}

    {% block sidebar %}{% endblock %}
    {% block title %}{% endblock %}
    {% block content %}{% endblock %}

.. note::

    The ``use`` tag only imports a template if it does not extend another
    template, if it does not define macros, and if the body is empty. But it
    can *use* other templates.

.. note::

    Because ``use`` statements are resolved independently of the context
    passed to the template, the template reference cannot be an expression.

The main template can also override any imported block. If the template
already defines the ``sidebar`` block, then the one defined in ``blocks.html``
is ignored. To avoid name conflicts, you can rename imported blocks:

.. code-block:: twig

    {% extends "base.html" %}

    {% use "blocks.html" with sidebar as base_sidebar, title as base_title %}

    {% block sidebar %}{% endblock %}
    {% block title %}{% endblock %}
    {% block content %}{% endblock %}

The ``parent()`` function automatically determines the correct inheritance
tree, so it can be used when overriding a block defined in an imported
template:

.. code-block:: twig

    {% extends "base.html" %}

    {% use "blocks.html" %}

    {% block sidebar %}
        {{ parent() }}
    {% endblock %}

    {% block title %}{% endblock %}
    {% block content %}{% endblock %}

In this example, ``parent()`` will correctly call the ``sidebar`` block from
the ``blocks.html`` template.

.. tip::

    Renaming allows you to simulate inheritance by calling the "parent" block:

    .. code-block:: twig

        {% extends "base.html" %}

        {% use "blocks.html" with sidebar as parent_sidebar %}

        {% block sidebar %}
            {{ block('parent_sidebar') }}
        {% endblock %}

.. note::

    You can use as many ``use`` statements as you want in any given template.
    If two imported templates define the same block, the latest one wins.