Matthias Andreas Benkard | 12a5735 | 2021-12-28 18:02:04 +0100 | [diff] [blame^] | 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 | |
| 10 | Template inheritance is one of the most powerful features of Twig but it is |
| 11 | limited to single inheritance; a template can only extend one other template. |
| 12 | This limitation makes template inheritance simple to understand and easy to |
| 13 | debug: |
| 14 | |
| 15 | .. code-block:: twig |
| 16 | |
| 17 | {% extends "base.html" %} |
| 18 | |
| 19 | {% block title %}{% endblock %} |
| 20 | {% block content %}{% endblock %} |
| 21 | |
| 22 | Horizontal reuse is a way to achieve the same goal as multiple inheritance, |
| 23 | but 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 | |
| 34 | The ``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 | |
| 43 | In this example, the ``use`` statement imports the ``sidebar`` block into the |
| 44 | main template. The code is mostly equivalent to the following one (the |
| 45 | imported 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 | |
| 66 | The main template can also override any imported block. If the template |
| 67 | already defines the ``sidebar`` block, then the one defined in ``blocks.html`` |
| 68 | is 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 | |
| 80 | The ``parent()`` function automatically determines the correct inheritance |
| 81 | tree, so it can be used when overriding a block defined in an imported |
| 82 | template: |
| 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 | |
| 97 | In this example, ``parent()`` will correctly call the ``sidebar`` block from |
| 98 | the ``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. |