Macros vs Includes

Question

Is there any guidance or pitfalls/benefits of using one over another? I see that includes can be done more or less the same way a Macro can be done (certainly for simple variable changes).

An example being with a series of social sharing links. So I currently have the following setup as an include like so;

<ul class="social-list">
    <li>
        <a href="https://twitter.com//intent/tweet/?text={{ object.title }}&amp;url={{ craft.request.url|url_encode }}&amp;via={{ socialMedia.twitter }}" target="_blank" title="Share on Twitter" class="js-social-share // track-social" data-label="Shared">
            <svg role="img" class="icon // icon-social  // icon-social--share // icon-twitter">
            <use xlink:href="/assets/img/icons.svg#share-twitter">Twitter</use>
            </svg>
        </a>
    </li>

    <li>
        <a href="https://www.facebook.com/sharer/sharer.php?u={{ craft.request.url|url_encode }}" target="_blank" title="Share on Facebook"  class="js-social-share // track-social" data-label="Shared">
            <svg role="img" class="icon // icon-social  // icon-social--share // icon-facebook">
            <use xlink:href="/assets/img/icons.svg#share-facebook">Facebook</use>
            </svg>
        </a>
    </li>

    <li>
        <a href="https://plus.google.com/share?url={{ craft.request.url|url_encode }}" target="_blank" title="Share on Google Plus" class="js-social-share // track-social" data-label="Shared">
            <svg role="img" class="icon // icon-social  // icon-social--share // icon-google-plus" class="js-social-share // track-social" data-label="Shared">
            <use xlink:href="/assets/img/icons.svg#share-googleplus">Google Plus</use>
            </svg>
        </a>
    </li>

    <li>
        <a href="mailto:?Subject={{ object.title }}&amp;Body=I%20saw%20this%20and%20thought%20it%20might%20be%20of%20interest! {{ craft.request.url|url_encode }}" title="Share via Email" class="track-social" data-label="Shared">
            <svg role="img" class="icon // icon-social  // icon-social--share // icon-share-email">
            <use xlink:href="/assets/img/icons.svg#share-email">Email</use>
            </svg>
        </a>
    </li>
</ul>

and then calling the file like so;

{% include '_includes/social-sharing' with { object : product } %}

But the same could easily be achieved using a Macro. Something I have previously used for something else, where an include would have also worked.

So is there a best case for when to use a Macro or an Include and what would be better in the above instance and why?

Thanks.

Answer 1

Fabien Potencier, the main developer of the Twig templating language answered the question like so:

• Macros: reusable markup across a lot of templates
• Includes: part of "pages" that are extracted for readability and reusability

The reason for this, as far as I understand, is that you can only use the include tag to render the complete file containing your partial. Whereas the macro tag allows to render a partial from a file with multiple macros / partials in it.

That being said, you are totally right in saying that both basically do the same thing. You can pass in variables, use them recursively, I do not know of a single thing one can do that the other can’t. Even performance shouldn’t be different really, at least within the context of Craft, as your Twig code gets compiled down to PHP and will then be cached.

What I personally do is to use macros for all the small things, something simple like the following example. I wouldn’t want to create a separate file for every little helper that allows me to keep things DRY.

{% macro icon(iconId) %}
    <svg class="icon icon-{{ iconId }}" role="img" title="{{ iconId }}">
        <use xlink:href="{{ url('assets/icons/icons.svg#icon-' ~ iconId) }}"></use>
    </svg>
{% endmacro %}

For larger chunks of code like a partial for a teaser card that I want to reuse throughout the site I’d definitly go with an include. I really want to have one dedicated file for each of these partials, main reason here is that I wouldn’t want any unrelated code in that file as they usually contain quite a lot of code. Another reason might be the better discoverability in the file structure.

Of course I could also setup files with only one macro in them instead. But then I’d end up with a bunch of import tags to load the macro files. So in the end it’s probably only a matter of the more appropriate syntax for each situation.

My project usually end up with between 20 and 100 partials for include tags, but I almost never have more than a single file for the macros.