include
The include tag will include another template within your theme folder and returns the rendered content from that template file into the current template.
NOTE - It's best to use it as a function because future versions of the Twig templating engine will require it to be a function instead of a tag.
A common use is to include a snippet template into another template.
{% include ('snippets/header') %}
<p>Our Page Body Here</p>
{% include ('snippets/footer') %}
You can, of course, include other templates as long as that template is within the theme base folder.
If the template that you are including is a Twig template then you do not have to specify the .twig extension, but you can if you want.
Accessing variables
Included templates have access to the variables of the active context.
You can pass additional variables to the included template by passing them through the with keyword.
{% include 'blog/custom-template' with {'variableName': 'variable value'} %}{% set vars = {
myVariable: 'my variable value',
anotherVar: 'Here is another variable'
} %}
{% include 'snippets/page-header' with vars %}You can disable access to the current content by using the only keyword. Any variables created within the included template will be available to that template, of course.
{# Template will only have the passed variables available to it #}
{% include 'blog/custom-template' with {'variableName': 'variable value'} only %}
{# No variables will be accessible to the template #}
{% include 'blog/custom-template' only %}Template names
The template name should start with it's folder path within the theme folder. Other than the site templates the template name should include at least one folder. For example, to include a snippet template you would include the snippet folder in the template name.
{% include ('snippets/header') %}If the template is a Twig template then you don't need to include the .twig file extension.
{% include ('snippets/header') %}
{# This does the same thing as the above tag #}
{% include ('snippets/header.twig') %}You can also dynamically set the template name because template names can be any valid Twig expression.
{% include (someVariable) %}
{% include (isAjax ? 'snippets/ajax' : 'snippets/full') %}You can also provide a list of templates to try and include. They are tested and the first one that is found will be included. The other templates in the list will be ignored. If none of the templates are found then an error will be displayed.
{% include (['template-name', 'alternate-template']) %}
{% include ['template-name', 'alternate-template'] with {'variable': 'value'} %}Handling missing templates
By default if an included template does not exist then an error is displayed that the template could not be found. You can, however, ignore missing templates and suppress displaying the error with the ignore missing keywords.
The ignore missing keywords have to be placed just after the template name.
{% include 'snippets/header' ignore missing %}
{% include 'snippets/header' ignore missing with {'var': 'value'} %}
{% include 'snippets/header' ignore missing with {'var': 'value'} only %}
{% include 'snippets/header' ignore missing only %}
{% include ['template-name', 'alternate-template'] ignore missing %}