aboutsummaryrefslogtreecommitdiffhomepage
path: root/vendor/twig/twig/doc/tags/use.rst
diff options
context:
space:
mode:
Diffstat (limited to 'vendor/twig/twig/doc/tags/use.rst')
-rw-r--r--vendor/twig/twig/doc/tags/use.rst123
1 files changed, 0 insertions, 123 deletions
diff --git a/vendor/twig/twig/doc/tags/use.rst b/vendor/twig/twig/doc/tags/use.rst
deleted file mode 100644
index 085f9161..00000000
--- a/vendor/twig/twig/doc/tags/use.rst
+++ /dev/null
@@ -1,123 +0,0 @@
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 Twig's feature 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 {% block sidebar %}{% endblock %}
44
45In this example, the ``use`` statement imports the ``sidebar`` block into the
46main template. The code is mostly equivalent to the following one (the
47imported blocks are not outputted automatically):
48
49.. code-block:: jinja
50
51 {% extends "base.html" %}
52
53 {% block sidebar %}{% endblock %}
54 {% block title %}{% endblock %}
55 {% block content %}{% endblock %}
56
57.. note::
58
59 The ``use`` tag only imports a template if it does not extend another
60 template, if it does not define macros, and if the body is empty. But it
61 can *use* other templates.
62
63.. note::
64
65 Because ``use`` statements are resolved independently of the context
66 passed to the template, the template reference cannot be an expression.
67
68The main template can also override any imported block. If the template
69already defines the ``sidebar`` block, then the one defined in ``blocks.html``
70is ignored. To avoid name conflicts, you can rename imported blocks:
71
72.. code-block:: jinja
73
74 {% extends "base.html" %}
75
76 {% use "blocks.html" with sidebar as base_sidebar %}
77
78 {% block sidebar %}{% endblock %}
79 {% block title %}{% endblock %}
80 {% block content %}{% endblock %}
81
82.. versionadded:: 1.3
83 The ``parent()`` support was added in Twig 1.3.
84
85The ``parent()`` function automatically determines the correct inheritance
86tree, so it can be used when overriding a block defined in an imported
87template:
88
89.. code-block:: jinja
90
91 {% extends "base.html" %}
92
93 {% use "blocks.html" %}
94
95 {% block sidebar %}
96 {{ parent() }}
97 {% endblock %}
98
99 {% block title %}{% endblock %}
100 {% block content %}{% endblock %}
101
102In this example, ``parent()`` will correctly call the ``sidebar`` block from
103the ``blocks.html`` template.
104
105.. tip::
106
107 In Twig 1.2, renaming allows you to simulate inheritance by calling the
108 "parent" block:
109
110 .. code-block:: jinja
111
112 {% extends "base.html" %}
113
114 {% use "blocks.html" with sidebar as parent_sidebar %}
115
116 {% block sidebar %}
117 {{ block('parent_sidebar') }}
118 {% endblock %}
119
120.. note::
121
122 You can use as many ``use`` statements as you want in any given template.
123 If two imported templates define the same block, the latest one wins.