www.aleph1.co.uk Git - yaffs-website/blob - vendor/twig/twig/doc/tags/include.rst

   1 ``include``
   2 ===========
   3
   4 The ``include`` statement includes a template and returns 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`` or a
  54 ``Twig_TemplateWrapper`` instance, Twig will use it directly::
  55
  56     // {% include template %}
  57
  58     // deprecated as of Twig 1.28
  59     $template = $twig->loadTemplate('some_template.twig');
  60
  61     // as of Twig 1.28
  62     $template = $twig->load('some_template.twig');
  63
  64     $twig->display('template.twig', array('template' => $template));
  65
  66 .. versionadded:: 1.2
  67     The ``ignore missing`` feature has been added in Twig 1.2.
  68
  69 You can mark an include with ``ignore missing`` in which case Twig will ignore
  70 the statement if the template to be included does not exist. It has to be
  71 placed just after the template name. Here some valid examples:
  72
  73 .. code-block:: jinja
  74
  75     {% include 'sidebar.html' ignore missing %}
  76     {% include 'sidebar.html' ignore missing with {'foo': 'bar'} %}
  77     {% include 'sidebar.html' ignore missing only %}
  78
  79 .. versionadded:: 1.2
  80     The possibility to pass an array of templates has been added in Twig 1.2.
  81
  82 You can also provide a list of templates that are checked for existence before
  83 inclusion. The first template that exists will be included:
  84
  85 .. code-block:: jinja
  86
  87     {% include ['page_detailed.html', 'page.html'] %}
  88
  89 If ``ignore missing`` is given, it will fall back to rendering nothing if none
  90 of the templates exist, otherwise it will throw an exception.