diff options
Diffstat (limited to 'vendor/twig/twig/doc/tags/include.rst')
-rw-r--r-- | vendor/twig/twig/doc/tags/include.rst | 86 |
1 files changed, 86 insertions, 0 deletions
diff --git a/vendor/twig/twig/doc/tags/include.rst b/vendor/twig/twig/doc/tags/include.rst new file mode 100644 index 00000000..10b262de --- /dev/null +++ b/vendor/twig/twig/doc/tags/include.rst | |||
@@ -0,0 +1,86 @@ | |||
1 | ``include`` | ||
2 | =========== | ||
3 | |||
4 | The ``include`` statement includes a template and return the rendered content | ||
5 | of that file into the current namespace: | ||
6 | |||
7 | .. code-block:: jinja | ||
8 | |||
9 | {% include 'header.html' %} | ||
10 | Body | ||
11 | {% include 'footer.html' %} | ||
12 | |||
13 | Included templates have access to the variables of the active context. | ||
14 | |||
15 | If you are using the filesystem loader, the templates are looked for in the | ||
16 | paths defined by it. | ||
17 | |||
18 | You can add additional variables by passing them after the ``with`` keyword: | ||
19 | |||
20 | .. code-block:: jinja | ||
21 | |||
22 | {# template.html will have access to the variables from the current context and the additional ones provided #} | ||
23 | {% include 'template.html' with {'foo': 'bar'} %} | ||
24 | |||
25 | {% set vars = {'foo': 'bar'} %} | ||
26 | {% include 'template.html' with vars %} | ||
27 | |||
28 | You can disable access to the context by appending the ``only`` keyword: | ||
29 | |||
30 | .. code-block:: jinja | ||
31 | |||
32 | {# only the foo variable will be accessible #} | ||
33 | {% include 'template.html' with {'foo': 'bar'} only %} | ||
34 | |||
35 | .. code-block:: jinja | ||
36 | |||
37 | {# no variables will be accessible #} | ||
38 | {% include 'template.html' only %} | ||
39 | |||
40 | .. tip:: | ||
41 | |||
42 | When including a template created by an end user, you should consider | ||
43 | sandboxing it. More information in the :doc:`Twig for Developers<../api>` | ||
44 | chapter and in the :doc:`sandbox<../tags/sandbox>` tag documentation. | ||
45 | |||
46 | The template name can be any valid Twig expression: | ||
47 | |||
48 | .. code-block:: jinja | ||
49 | |||
50 | {% include some_var %} | ||
51 | {% include ajax ? 'ajax.html' : 'not_ajax.html' %} | ||
52 | |||
53 | And if the expression evaluates to a ``Twig_Template`` object, Twig will use it | ||
54 | directly:: | ||
55 | |||
56 | // {% include template %} | ||
57 | |||
58 | $template = $twig->loadTemplate('some_template.twig'); | ||
59 | |||
60 | $twig->loadTemplate('template.twig')->display(array('template' => $template)); | ||
61 | |||
62 | .. versionadded:: 1.2 | ||
63 | The ``ignore missing`` feature has been added in Twig 1.2. | ||
64 | |||
65 | You can mark an include with ``ignore missing`` in which case Twig will ignore | ||
66 | the statement if the template to be included does not exist. It has to be | ||
67 | placed just after the template name. Here some valid examples: | ||
68 | |||
69 | .. code-block:: jinja | ||
70 | |||
71 | {% include 'sidebar.html' ignore missing %} | ||
72 | {% include 'sidebar.html' ignore missing with {'foo': 'bar'} %} | ||
73 | {% include 'sidebar.html' ignore missing only %} | ||
74 | |||
75 | .. versionadded:: 1.2 | ||
76 | The possibility to pass an array of templates has been added in Twig 1.2. | ||
77 | |||
78 | You can also provide a list of templates that are checked for existence before | ||
79 | inclusion. The first template that exists will be included: | ||
80 | |||
81 | .. code-block:: jinja | ||
82 | |||
83 | {% include ['page_detailed.html', 'page.html'] %} | ||
84 | |||
85 | If ``ignore missing`` is given, it will fall back to rendering nothing if none | ||
86 | of the templates exist, otherwise it will throw an exception. | ||