diff options
Diffstat (limited to 'vendor/twig/twig/doc/tags/use.rst')
-rw-r--r-- | vendor/twig/twig/doc/tags/use.rst | 123 |
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 | |||
13 | Template inheritance is one of the most powerful Twig's feature but it is | ||
14 | limited to single inheritance; a template can only extend one other template. | ||
15 | This limitation makes template inheritance simple to understand and easy to | ||
16 | debug: | ||
17 | |||
18 | .. code-block:: jinja | ||
19 | |||
20 | {% extends "base.html" %} | ||
21 | |||
22 | {% block title %}{% endblock %} | ||
23 | {% block content %}{% endblock %} | ||
24 | |||
25 | Horizontal reuse is a way to achieve the same goal as multiple inheritance, | ||
26 | but 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 | |||
37 | The ``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 | |||
45 | In this example, the ``use`` statement imports the ``sidebar`` block into the | ||
46 | main template. The code is mostly equivalent to the following one (the | ||
47 | imported 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 | |||
68 | The main template can also override any imported block. If the template | ||
69 | already defines the ``sidebar`` block, then the one defined in ``blocks.html`` | ||
70 | is 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 | |||
85 | The ``parent()`` function automatically determines the correct inheritance | ||
86 | tree, so it can be used when overriding a block defined in an imported | ||
87 | template: | ||
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 | |||
102 | In this example, ``parent()`` will correctly call the ``sidebar`` block from | ||
103 | the ``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. | ||