When to use include, extends, and embed

This is just a placeholder (and reminder) to document the proper use of include, extends, and embed.

With a link.twig file like this:

  {% block link_content %}
    {{ link_content }}
  {% endblock %}
</a>

You can use it in another template one of the following ways

Replace the variables (ignoring the block)

Standard "use another component but change the variables."

{% include "@atoms/01-links/link/link.twig"
  with {
    "link_content": "This is included",
    "link_url": "https://www.fourkitchens.com",
  }
%}

Replace the block (ignores the variable inside the block)

This would be useful if you wanted to link something other than text, like an image. The image include would go inside the block.

{% extends "@atoms/01-links/link/link.twig" %}
  {% block link_content %}
    {% include "@atoms/04-images/00-image/image.twig"
      with {
        "img_src": "http://placeimg.com/1200/800/tech",
      }
    %}
  {% endblock %}

The problem is, link also wants a url, and has optional class modifiers, so we need to be able to replace the block, and the variables.

Use embed to replace the variables, but still have the option to replace the whole block

{% embed "@atoms/01-links/link/link.twig"
  with {
    "link_url": "https://www.fourkitchens.com",
  }
%}
  {% block link_content %}
    {% include "@atoms/04-images/00-image/image.twig"
      with {
        "img_src": "http://placeimg.com/1200/800/tech",
        "img_alt": "This is the image alt text",
      }
    %}
  {% endblock %}
{% endembed %}