1``include``
2===========
3
4The ``include`` statement includes a template and returns the rendered content
5of that file:
6
7.. code-block:: jinja
8
9    {% include 'header.html' %}
10        Body
11    {% include 'footer.html' %}
12
13.. note::
14
15    As of Twig 1.12, it is recommended to use the
16    :doc:`include<../functions/include>` function instead as it provides the
17    same features with a bit more flexibility:
18
19    * The ``include`` function is semantically more "correct" (including a
20      template outputs its rendered contents in the current scope; a tag should
21      not display anything);
22
23    * The rendered template can be more easily stored in a variable when using
24      the ``include`` function:
25
26      .. code-block:: jinja
27
28          {% set content %}{% include 'template.html' %}{% endset %}
29
30          {# vs #}
31
32          {% set content = include('template.html') %}
33
34    * The ``include`` function does not impose any specific order for
35      arguments thanks to :ref:`named arguments <named-arguments>`.
36
37Included templates have access to the variables of the active context.
38
39If you are using the filesystem loader, the templates are looked for in the
40paths defined by it.
41
42You can add additional variables by passing them after the ``with`` keyword:
43
44.. code-block:: jinja
45
46    {# template.html will have access to the variables from the current context and the additional ones provided #}
47    {% include 'template.html' with {'foo': 'bar'} %}
48
49    {% set vars = {'foo': 'bar'} %}
50    {% include 'template.html' with vars %}
51
52You can disable access to the context by appending the ``only`` keyword:
53
54.. code-block:: jinja
55
56    {# only the foo variable will be accessible #}
57    {% include 'template.html' with {'foo': 'bar'} only %}
58
59.. code-block:: jinja
60
61    {# no variables will be accessible #}
62    {% include 'template.html' only %}
63
64.. tip::
65
66    When including a template created by an end user, you should consider
67    sandboxing it. More information in the :doc:`Twig for Developers<../api>`
68    chapter and in the :doc:`sandbox<../tags/sandbox>` tag documentation.
69
70The template name can be any valid Twig expression:
71
72.. code-block:: jinja
73
74    {% include some_var %}
75    {% include ajax ? 'ajax.html' : 'not_ajax.html' %}
76
77And if the expression evaluates to a ``\Twig\Template`` or a
78``\Twig\TemplateWrapper`` instance, Twig will use it directly::
79
80    // {% include template %}
81
82    // deprecated as of Twig 1.28
83    $template = $twig->loadTemplate('some_template.twig');
84
85    // as of Twig 1.28
86    $template = $twig->load('some_template.twig');
87
88    $twig->display('template.twig', ['template' => $template]);
89
90.. versionadded:: 1.2
91    The ``ignore missing`` feature has been added in Twig 1.2.
92
93You can mark an include with ``ignore missing`` in which case Twig will ignore
94the statement if the template to be included does not exist. It has to be
95placed just after the template name. Here some valid examples:
96
97.. code-block:: jinja
98
99    {% include 'sidebar.html' ignore missing %}
100    {% include 'sidebar.html' ignore missing with {'foo': 'bar'} %}
101    {% include 'sidebar.html' ignore missing only %}
102
103.. versionadded:: 1.2
104    The possibility to pass an array of templates has been added in Twig 1.2.
105
106You can also provide a list of templates that are checked for existence before
107inclusion. The first template that exists will be included:
108
109.. code-block:: jinja
110
111    {% include ['page_detailed.html', 'page.html'] %}
112
113If ``ignore missing`` is given, it will fall back to rendering nothing if none
114of the templates exist, otherwise it will throw an exception.
115