Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

include, embed and macros – when to use which for reuse? #1697

Closed
mpdude opened this issue May 28, 2015 · 3 comments

Comments

@mpdude
Copy link
Contributor

commented May 28, 2015

This is a question my frontend guys ask me quite often and to be honest, I don't have a good one-size-fits-all answer. Unfortunately, the docs aren't helpful either.

So, the following blocks of code roughly do the same:

include

# someFile.html.twig
{% set foo = "Foo!" %}
{% set bar %} {# <-- omit this assignment if you want the default #}
   even more bar
{% endset %}
{% include "reused.html.twig" %}

# reused.html.twig
<h1>{{ foo }} </h1>
<p>Some common stuff.</p>
{% if bar %}
    {{ bar | raw }} 
{% else %}
    <p>Default text for bar.</p>
{% endif %}

embed

# someFile.html.twig
{% embed "reused.html.twig" %}
    {% block foo %} Foo! {% endblock %}
    {% block bar %} {# <-- again, this may be omitted #}
       even more bar
    {% endblock %}
{% endembed %}

# reused.html.twig
<h1>{% block foo %}{% endblock %} </h1>
<p>Some common stuff.</p>
{% block bar %}
    <p>Default text for bar.</p>
{% endblock %}

macro

# someFile.html.twig
{% import "reused.html.twig" as macros %}
{% set bar %} {# <-- omit this assignment if you want the default #}
   even more bar
{% endset %}
{{ macros.someBlock("Foo!", bar) }}

# reused.html.twig
{% macro someBlock(foo, bar) %}
<h1>{{ foo }} </h1>
<p>Some common stuff.</p>
{% if bar %}
    {{ bar | raw }} 
{% else %}
    <p>Default text for bar.</p>
{% endif %}
{% endmacro %}

There are many pros and cons for all of those approaches, including readablility, conciseness or the benefits of having an explicit interface (macro signature) and the benefits of encapsulation/scoping variables.

Are there any recommendations or is there a good rule of thumb when to use which?

Needless to say I'd be glad to write the doc PR if we get a good result here :-).

@stof

This comment has been minimized.

Copy link
Contributor

commented May 28, 2015

Regarding include vs embed, the choice between them is easy: if you need to overwrite some blocks of the included template, use embed (this is the goal of this tag). If you don't need to overwrite blocks, use include. It will do the same in a faster way.

Regarding the scoping of variables, this is also possible with include or embed: http://twig.sensiolabs.org/doc/tags/include.html

Regarding the use case for macros, I will let other answer, as I actually don't use them much.

@fabpot

This comment has been minimized.

Copy link
Contributor

commented Jun 28, 2015

Macros: reusable markup across a lot of templates
Includes: part of "pages" that are extracted for readability and reusability
Embed: @stof explained when it's useful (block overriding)

@Jero786

This comment has been minimized.

Copy link

commented Jan 15, 2019

I think this is a interesting blog about macros/includes using component approach.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
4 participants
You can’t perform that action at this time.