[Twig] How to Use Macros (with Examples)

Twig macros are equivalent to functions in regular programming languages. They allow you to turn frequently used HTML structures into reusable components.

Simply put, it's like being able to template HTML elements such as buttons that you use repeatedly.

Official: macro - Documentation

HOW TO WRITE MACROS

{% macro basic_button(url, label, marginClass = "mb-3", width = 200) %}
    <a href="{{ url }}" class="btn btn-primary {{ marginClass }}" style="width: {{ width }}px;">
        {{ label }}
    </a>
{% endmacro %}

You can also set default values by pre-entering values with `=`.

The arguments you define can be used as variables within the macro, just like regular Twig variables.

Conversely, variables from the calling scope that are not set as arguments cannot be used within the macro.

HOW TO CALL AND USE MACROS

Here's how to call the macros you've created. In addition to defining them within the same Twig file, it's also possible to define macros in external files.

How to Call a Macro within the Same Twig File

{{ _self.basic_button('/homepage', 'test button') }}

// result
<a href="/homepage" class="btn btn-primary mb-3" style="width: 200;"> test button </a>

Macros within the same file can be accessed using `_self`.

In the example above, we are calling the macro named `basic_button` that we created earlier. Values are passed to the `url` and `label` arguments.

// define _self as button
{% import _self as button %}

// call macro
{{ button.basic_button('/homepage', 'test button', 'mb-5', 300) }}

How to Call a Macro from an External File (import)

If the macro created above was defined in a file named `button_macro.twig`:

{% import "button_macro.twig" as button %}

// call macro
{{ button.basic_button('/homepage', 'test button', 'mb-5', 300) }}

Creating macros in external files is convenient because you can reuse the macros themselves in other Twig templates.

How to Call a Macro from an External File (from)

You can also call the macro directly or by assigning it a new name.

{% from 'button_macro.html' import basic_button as basic %}

// call macro
{{ basic('/homepage', 'test button', 'mb-5', 300) }}

In the sample above, the `basic_button` macro is called with the new name `basic`.

Unlike `include`, I think it's good that you can create macros with the intent of making simple components. While `include` can't load multiple items at once, macros allow you to load multiple macros into a Twig template simultaneously if they are all placed in one file. This should also make coding easier, so please give it a try.

RECOMMENDED TWIG BOOKS

I haven't read any books specifically dedicated to Twig, but I found one on Amazon Kindle.