[github/wallabag/wallabag.git] / vendor / twig / twig / doc / tags / include.rst

``include``
===========

The ``include`` statement includes a template and return the rendered content
of that file into the current namespace:

.. code-block:: jinja

    {% include 'header.html' %}
        Body
    {% include 'footer.html' %}

Included templates have access to the variables of the active context.

If you are using the filesystem loader, the templates are looked for in the
paths defined by it.

You can add additional variables by passing them after the ``with`` keyword:

.. code-block:: jinja

    {# template.html will have access to the variables from the current context and the additional ones provided #}
    {% include 'template.html' with {'foo': 'bar'} %}

    {% set vars = {'foo': 'bar'} %}
    {% include 'template.html' with vars %}

You can disable access to the context by appending the ``only`` keyword:

.. code-block:: jinja

    {# only the foo variable will be accessible #}
    {% include 'template.html' with {'foo': 'bar'} only %}

.. code-block:: jinja

    {# no variables will be accessible #}
    {% include 'template.html' only %}

.. tip::

    When including a template created by an end user, you should consider
    sandboxing it. More information in the :doc:`Twig for Developers<../api>`
    chapter and in the :doc:`sandbox<../tags/sandbox>` tag documentation.

The template name can be any valid Twig expression:

.. code-block:: jinja

    {% include some_var %}
    {% include ajax ? 'ajax.html' : 'not_ajax.html' %}

And if the expression evaluates to a ``Twig_Template`` object, Twig will use it
directly::

    // {% include template %}

    $template = $twig->loadTemplate('some_template.twig');

    $twig->loadTemplate('template.twig')->display(array('template' => $template));

.. versionadded:: 1.2
    The ``ignore missing`` feature has been added in Twig 1.2.

You can mark an include with ``ignore missing`` in which case Twig will ignore
the statement if the template to be included does not exist. It has to be
placed just after the template name. Here some valid examples:

.. code-block:: jinja

    {% include 'sidebar.html' ignore missing %}
    {% include 'sidebar.html' ignore missing with {'foo': 'bar'} %}
    {% include 'sidebar.html' ignore missing only %}

.. versionadded:: 1.2
    The possibility to pass an array of templates has been added in Twig 1.2.

You can also provide a list of templates that are checked for existence before
inclusion. The first template that exists will be included:

.. code-block:: jinja

    {% include ['page_detailed.html', 'page.html'] %}

If ``ignore missing`` is given, it will fall back to rendering nothing if none
of the templates exist, otherwise it will throw an exception.
Commit	Line	Data
4f5b44bd NL	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.