mirror of
https://github.com/twigphp/Twig.git
synced 2026-08-30 12:06:56 +00:00
Fabien Potencier
f640320202
* 3.x: (26 commits) Remove the documentation comments compilation overhead Clarify source function trust requirements Throw on PCRE errors in the matches operator Document that reusing a non-rewindable iterator after destructuring is unsupported Release destructuring temporaries after assignment Deprecate prefixed macro definedness checks Fix duplicate macro deprecation wording Throw when list formatting fails Document that sequence destructuring consumes one value per pattern slot Fix the html_attr documentation about iterables in data attributes Warn about untrusted input with the default Tempest markdown converter Document that overriding MacroNode::compile() is not supported anymore Merge overlapping CHANGELOG entries for the destructuring fatal error fix Document that include_only keeps global variables available Remove lazy macro import resolution Honor date formatter prototype calendars Fix Stringable keys for ArrayAccess implementations Fix repeated object destructuring evaluation Restore void return type compatibility for extension points Reject destructuring patterns containing no variables ... # Conflicts: # CHANGELOG # doc/deprecated.rst # doc/filters/format_datetime.rst # extra/twig-extra-bundle/DependencyInjection/Compiler/MissingExtensionSuggestorPass.php # extra/twig-extra-bundle/DependencyInjection/TwigExtraExtension.php # extra/twig-extra-bundle/TwigExtraBundle.php # src/MacroNamespace.php # src/Node/MacrosNode.php # src/Parser.php # src/Test/IntegrationTestCase.php # src/Test/NodeTestCase.php # tests/CallMacroTest.php # tests/ExpressionParserTest.php # tests/Fixtures/macros/duplicate_definition.legacy.test # tests/Node/MacrosTest.php # tests/ParserTest.php
97 lines
2.8 KiB
ReStructuredText
97 lines
2.8 KiB
ReStructuredText
``include_only``
|
|
================
|
|
|
|
The ``include_only`` function returns the rendered content of a template
|
|
without giving it access to the current context:
|
|
|
|
.. code-block:: twig
|
|
|
|
{{ include_only('template.html.twig') }}
|
|
{{ include_only(some_var) }}
|
|
|
|
Variables from the active context are not passed implicitly. This makes the
|
|
data a template relies on explicit, which is often clearer and easier to
|
|
reason about.
|
|
|
|
Note that global variables (like the ones registered via ``addGlobal()``) are
|
|
not part of the context: they remain available in the included template.
|
|
|
|
Returned Value
|
|
--------------
|
|
|
|
The returned content is a ``\Twig\Markup`` instance, so it is considered safe
|
|
and is not escaped again when you store it in a variable and print it later:
|
|
|
|
.. code-block:: twig
|
|
|
|
{% set body = include_only('body.html.twig') %}
|
|
{{ body }} {# rendered as-is, not re-escaped #}
|
|
|
|
Beware that, like any safe value, it is not re-escaped for the context it ends
|
|
up in, so only embed it in the same context it was rendered for (typically
|
|
HTML).
|
|
|
|
Passing Variables
|
|
-----------------
|
|
|
|
As the context is not passed, variables a template needs must be passed
|
|
explicitly:
|
|
|
|
.. code-block:: twig
|
|
|
|
{# template.html.twig only gets the "name" variable from the caller #}
|
|
{{ include_only('template.html.twig', {name: 'Fabien'}) }}
|
|
|
|
When passing a variable from the current context, you can use the following
|
|
shortcut:
|
|
|
|
.. code-block:: twig
|
|
|
|
{{ include_only('template.html.twig', {name, email}) }}
|
|
|
|
{# is equivalent to #}
|
|
|
|
{{ include_only('template.html.twig', {name: name, email: email}) }}
|
|
|
|
Loading Templates
|
|
-----------------
|
|
|
|
If you are using the filesystem loader, the templates are looked for in the
|
|
paths defined by it.
|
|
|
|
If the expression evaluates to a ``\Twig\TemplateWrapper`` instance, Twig
|
|
will use it directly::
|
|
|
|
// {{ include_only(template) }}
|
|
|
|
$template = $twig->load('some_template.html.twig');
|
|
|
|
$twig->display('template.html.twig', ['template' => $template]);
|
|
|
|
When you set the ``ignore_missing`` flag, Twig will return an empty string if
|
|
the template does not exist:
|
|
|
|
.. code-block:: twig
|
|
|
|
{{ include_only('sidebar.html.twig', ignore_missing: true) }}
|
|
|
|
You can also provide a list of templates that are checked for existence before
|
|
inclusion. The first template that exists will be rendered:
|
|
|
|
.. code-block:: twig
|
|
|
|
{{ include_only(['page_detailed.html.twig', 'page.html.twig']) }}
|
|
|
|
If ``ignore_missing`` is set, it will fall back to rendering nothing if none
|
|
of the templates exist, otherwise it will throw an exception.
|
|
|
|
To render a template created by an end user, use the
|
|
:doc:`render_sandboxed() function </functions/render_sandboxed>`.
|
|
|
|
Arguments
|
|
---------
|
|
|
|
* ``template``: The template to render
|
|
* ``variables``: The variables to pass to the template
|
|
* ``ignore_missing``: Whether to ignore missing templates or not
|