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