Answers.Body: <p>Fabien Potencier, the main developer of the Twig templating language <a href="https://github.com/twigphp/Twig/issues/1697">answered the question</a> like so:</p>
  
  <blockquote>
    <ul>
    <li>Macros: reusable markup across a lot of templates</li>
    <li>Includes: part of "pages" that are extracted for readability and reusability</li>
    </ul>
  </blockquote>
  
  <p>The reason for this, as far as I understand, is that you can only use the <code>include</code> tag to render the complete file containing your partial. Whereas the <code>macro</code> tag allows to render a partial from a file with multiple macros / partials in it.</p>
  
  <p>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.</p>
  
  <p>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.</p>
  
  <pre><code>{% macro icon(iconId) %}
      &lt;svg class="icon icon-{{ iconId }}" role="img" title="{{ iconId }}"&gt;
          &lt;use xlink:href="{{ url('assets/icons/icons.svg#icon-' ~ iconId) }}"&gt;&lt;/use&gt;
      &lt;/svg&gt;
  {% endmacro %}
  </code></pre>
  
  <p>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 <code>include</code>. 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.</p>
  
  <p>Of course I could also setup files with only one macro in them instead. But then I’d end up with a bunch of <code>import</code> tags to load the macro files. So in the end it’s probably only a matter of the more appropriate syntax for each situation.</p>
  
  <p>My project usually end up with between 20 and 100 partials for <code>include</code> tags, but I almost never have more than a single file for the macros.</p>
  
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2016-07-23T16:59:47.160Z
Answers.Text: Thanks @carlcs this makes great sense and is explained very well. I also like the SVG icon macro. I might incorporate that one :-)
Answers.UserDisplayName: Terry Upton
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2016-07-23T15:46:18.127Z
Answers.LastActivityDate: 2016-07-23T18:02:27.877Z
Answers.LastEditDate: 2016-07-23T18:02:27.877Z
Answers.UserDisplayName: carlcs
Body: <p>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).</p>
  
  <p>An example being with a series of social sharing links.
  So I currently have the following setup as an include like so;</p>
  
  <pre><code>&lt;ul class="social-list"&gt;
      &lt;li&gt;
          &lt;a href="https://twitter.com//intent/tweet/?text={{ object.title }}&amp;amp;url={{ craft.request.url|url_encode }}&amp;amp;via={{ socialMedia.twitter }}" target="_blank" title="Share on Twitter" class="js-social-share // track-social" data-label="Shared"&gt;
              &lt;svg role="img" class="icon // icon-social  // icon-social--share // icon-twitter"&gt;
              &lt;use xlink:href="/assets/img/icons.svg#share-twitter"&gt;Twitter&lt;/use&gt;
              &lt;/svg&gt;
          &lt;/a&gt;
      &lt;/li&gt;
  
      &lt;li&gt;
          &lt;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"&gt;
              &lt;svg role="img" class="icon // icon-social  // icon-social--share // icon-facebook"&gt;
              &lt;use xlink:href="/assets/img/icons.svg#share-facebook"&gt;Facebook&lt;/use&gt;
              &lt;/svg&gt;
          &lt;/a&gt;
      &lt;/li&gt;
  
      &lt;li&gt;
          &lt;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"&gt;
              &lt;svg role="img" class="icon // icon-social  // icon-social--share // icon-google-plus" class="js-social-share // track-social" data-label="Shared"&gt;
              &lt;use xlink:href="/assets/img/icons.svg#share-googleplus"&gt;Google Plus&lt;/use&gt;
              &lt;/svg&gt;
          &lt;/a&gt;
      &lt;/li&gt;
  
      &lt;li&gt;
          &lt;a href="mailto:?Subject={{ object.title }}&amp;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"&gt;
              &lt;svg role="img" class="icon // icon-social  // icon-social--share // icon-share-email"&gt;
              &lt;use xlink:href="/assets/img/icons.svg#share-email"&gt;Email&lt;/use&gt;
              &lt;/svg&gt;
          &lt;/a&gt;
      &lt;/li&gt;
  &lt;/ul&gt;
  </code></pre>
  
  <p>and then calling the file like so;</p>
  
  <pre><code>{% include '_includes/social-sharing' with { object : product } %}
  </code></pre>
  
  <p>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.</p>
  
  <p>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?</p>
  
  <p>Thanks.</p>
  
Comments.ContentLicense: CC BY-SA 3.0
Comments.CreationDate: 2016-07-23T15:56:51.317Z
Comments.Text: Yep, I would have used an include for this as well.
Comments.UserDisplayName: carlcs
Tags: <templating><best-practice><macro><include>
Title: Macros vs Includes
ThreadText: # Macros vs Includes
  
  (Asked by: username_0 on 2016-07-23)
  
  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.
  
  **Tags:** templating, best-practice, macro, include
  
  > **Comments:**
  > **username_1**: Yep, I would have used an include for this as well.  
  
  ---
  
  ## 1 answers
  
  ### Answer by username_1 on 2016-07-23. Score: 19 | Accepted answer
  
  Fabien Potencier, the main developer of the Twig templating language [answered the question](https://github.com/twigphp/Twig/issues/1697) 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.
  
  > **Comments:**
  > **username_0**: Thanks @username_1 this makes great sense and is explained very well. I also like the SVG icon macro. I might incorporate that one :-)  
  
  ---
  
  