Macros
Macros in Twig are a powerful way to define reusable blocks of code that can be invoked with different arguments throughout your templates. This feature is particularly useful for repetitive HTML elements or complex UI components. In ShopWired themes, we use macros extensively to simplify the rendering of common elements like forms, buttons, and scripts.
Defining and Using Macros
Macros are defined within a Twig template using the {% macro %} tag. Once defined, they can be called like a function within the same template or even imported into other templates.
HTML Macros
In ShopWired themes, the html.twig file contains several macros to streamline the inclusion of common HTML elements. Here are a few examples:
Stylesheet Macro
The stylesheet macro is used to include a CSS stylesheet, with an option to preload it for performance improvements.
Macro definition in html.twig:
{% macro stylesheet(url, async) %}
<link rel="{{ async ? 'preload' : 'stylesheet' }}" href="{{ url }}"{% if async %} as="style" onload="this.rel='stylesheet'"{% endif %}>
{% endmacro %}
{{ html.stylesheet(asset_url('scss/theme.css')) }}
Script Macro
The script macro simplifies the inclusion of JavaScript files, allowing you to pass additional attributes if needed.
Macro definition in html.twig:
{% macro script(url, attribute) %}
<script src="{{ url }}"{{ attribute ? ' ' ~ attribute : '' }}></script>
{% endmacro %}
Usage example:
{{ html.script(asset_url('js/application.js')) }}
Theme Macros
In the theme.twig file, macros are used to manage theme-specific elements like text snippets, product labels, and form fields. These macros help maintain consistency across different parts of the theme while allowing for easy customisation.
Text Snippet Macro
The text_snippet macro is used to render text with placeholders that can be replaced dynamically, such as the current year or business contact details.
Macro definition in theme.twig:
{% macro text_snippet(name, raw, settings_object) %}
{% set short_codes = {
'[[YEAR]]': 'now'|date('Y'),
'[[EMAIL]]': global.business.email,
'[[PHONE]]': global.business.phone,
'[[ADDRESS]]': global.business.one_line_address
} %}
{% if global.theme.is_preview_mode_enabled %}
<span data-name="text_{{ name }}" id="text_{{ name }}"{{ not raw ? 'class="html-snippet"' : '' }}>
{% endif %}
{% set parent_obj = settings_object ? settings_object : global.theme.settings %}
{% if raw %}
{{ parent_obj['text_' ~ name]|replace(short_codes) }}
{% else %}
{{ parent_obj['text_' ~ name]|replace(short_codes)|raw }}
{% endif %}
{% if global.theme.is_preview_mode_enabled %}
</span>
{% endif %}
{% endmacro %}
Usage example:
{{ text_snippet('welcome_message', false) }}
This macro will render a welcome message, replacing placeholders like [[YEAR]] with the current year.
Product Label Macro
The product_label macro is used to display different types of product labels, such as "New" or "3 for 2".
Macro definition in theme.twig:
{% macro product_label(name, classes) %}
{% if name == '3 for 2' %}
<span class="label primary three-for-two{{ classes ? ' ' ~ classes : '' }}">3for2</span>
{% elseif name == '2 for 1' %}
<span class="label primary two-for-one{{ classes ? ' ' ~ classes : '' }}">2for1</span>
{% elseif name == 'new' %}
<div class="label secondary new{{ classes ? ' ' ~ classes : '' }}">New</div>
{% endif %}
{% endmacro %}
Usage example:
{{ product_label('new', 'highlight') }}
This will generate:
<div class="label secondary new highlight">New</div>
Importing Macros
If you need to use macros defined in one template within another, you can import them using the import tag. This is useful for sharing macros across different parts of your theme.
Example of importing macros:
{% import 'macros/html.twig' as html %}
{{ html.stylesheet(asset_url('scss/theme.css')) }}
In this example, the stylesheet macro from html.twig is imported and used in another template.
