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