{% include 'cart.inc.twig' %}
=== Embed - output the include on the page, but allowing for overriding blocks within it ===
Loading an include using ''embed'' behaves similar to ''include'' above in that it will output the whole contents of the file into the page. Within the ''embed'' tags though, you can also define ''block'' tags for blocks that exist within that included file, and overwrite them. Any code not contained with a pre-existing block, or any custom blocks, will be ignored. [[https://twig.symfony.com/doc/2.x/tags/embed.html|View embed in the Twig documentation]].
Example:
{% embed 'checkout.inc.twig' %}
{% endembed %}
=== Use - load the blocks contained within ready for placement and modifying ===
Referencing an include using ''use'', with just that tag in isolation will output nothing into the page. What it will do is gather all the blocks within that include and load them into memory for you to manually include as desired. Anything not contained inside blocks will be ignored. [[https://twig.symfony.com/doc/2.x/tags/use.html|View use in the Twig documentation]].
Example:
{% use 'cart.inc.twig' %}
{# Nothing output yet #}
{{ block('logo') }}
{# Logo block output into page #}
==== Blocks ====
Within the partial templates, we make use of [[https://twig.symfony.com/doc/2.x/tags/block.html|Twig's block functionality]] to wrap certain chunks of our code into a named block. For an example, let's say you have a partial include called ''widgets.inc.twig'' with blocks that look like this:
{% block block_a %}
{{ widget_title }}
{% endblock block_a %}
{% block block_b %}
{{ widget_subtitle }}
{% endblock block_b %}
As you can see, there are two blocks within that markup enclosing two headers. If you wanted to just include that whole partial in your page template, you would just use the ''include'' approach to do that. What if you wanted to include that partial, but make some changes to one of the blocks? That's where ''use'' comes into play - allowing you to reference whole blocks with a single tag.
=== Editing blocks with ''embed'' ===
As an example, let's say that we wanted to output our ''widgets.inc.twig'' partial within our page, but we wanted to change ''block_b'' to output the ''widget_subtitle'' in a paragraph tag instead of a heading. We don't want to change ''block_a'' at all. We could simply copy the whole ''widgets.inc.twig'' code into our partial and just ignore the blocks, which would work. A better way though is to make use of the ''embed'' tag, and overwrite blocks from the partial. By doing that - our code is cleaner within our page template, and if we make changes to our ''widgets.inc.twig'' partial file later on, we'll still get those changes (apart from anything we overwrite).
So to follow on with our example, changing the ''h2'' element to a paragraph would look like this in our page template:
{% embed 'widgets.inc.twig' %}
{% block block_b %}
{{ widget_subtitle }}
{% endblock block_b %}
{% endembed %}
In the code above - the ''widgets.inc.twig'' template will be output as it is in the original file, but ''block_b'' will be output as we redefined it within the ''embed''. This would result in HTML like this:
{{ widget_title }}
{{ widget_subtitle }}
Embedding also allows you to still output the block as it is - and just add something before or after it. For example, if we wanted to add some additional content after the ''h2'' title in ''block_b'', but leave the heading as it is, we can do that by outputting ''%%{{ parent() }}%%'' like this:
{% embed 'widgets.inc.twig' %}
{% block block_b %}
{{ parent() }}
{{ widget_date }}
{% endblock block_b %}
{% endembed %}
This set up would result in HTML like this:
{{ widget_title }}
{{ widget_subtitle }}
{{ widget_date }}