How template fallback works in the Hyvä theme

In this blog, we’ll explore how template fallback works in the Hyvä theme and understand how templates can be overridden in two ways:

1. In the Hyvä compatibility module.
2. In the Hyvä child theme.

Table of contents

Step 1: The template in the Hyvä compatibility module

Suppose a module named MyCompany_SampleModule contains the following template file:

<?php
/**
 * @var $block \Magento\Framework\View\Element\Template
 * @var $escaper \Magento\Framework\Escaper
 */
?>
<div class="row">
	<?= $escaper->escapeHtml(__('Hello, this is a sample block in a MyCompany_SampleModule::sampleblock.phtml module!')) ?>
</div>MyCompany_SampleModule/view/frontend/templates/sampleblock.phtml

This template file is overridden in the Hyvä compatibility module:

<?php
/**
 * @var $block \Magento\Framework\View\Element\Template
 * @var $escaper \Magento\Framework\Escaper
 */
?>
<div class="py-2">
	<?= $escaper->escapeHtml(__('Hello, this is a sample block in a Hyva_MyCompanySampleModule::sampleblock.phtml module!')) ?>
</div>Hyva_MyCompanySampleModule/view/frontend/templates/sampleblock.phtml

On the frontend, you’ll see the following text:

Hello, this is a sample block in a Hyva_MyCompanySampleModule::sampleblock.phtml module!

Step 2: Override the template in the Hyvä child theme under the Original module path

To override the template file from Hyva_MyCompanySampleModule::sampleblock.phtml in your Hyvä child theme, place your template under the original module path MyCompany_SampleModule rather than the Hyvä-compatible module path.

<?php
/**
 * @var $block \Magento\Framework\View\Element\Template
 * @var $escaper \Magento\Framework\Escaper
 */
?>
<div>
	<?= $escaper->escapeHtml(__('Hello, this is a sample block in a Hyva child theme MyCompany_SampleModule module!')) ?>
</div>app/design/frontend/MyCompany/child/MyCompany_SampleModule/templates/sampleblock.phtml

On the frontend, you’ll see:

Hello, this is a sample block in a Hyva child theme MyCompany_SampleModule module!

Step 3: Override the template in the Hyvä child theme under the Hyvä-compatible module path

To override the template file in the Hyvä child theme under the Hyvä-compatible module path, place the template file at:

<?php
/**
 * @var $block \Magento\Framework\View\Element\Template
 * @var $escaper \Magento\Framework\Escaper
 */
?>
<div>
    <?= $escaper->escapeHtml(__('Hello, this is a sample block in a Hyva child theme Hyva_MyCompanySampleModule module!')) ?>
</div>app/design/frontend/MyCompany/child/Hyva_MyCompanySampleModule/templates/sampleblock.phtml

Surprisingly, the frontend will display the text from the MyCompany_SampleModule::sampleblock.phtml template instead of Hyva_MyCompanySampleModule::sampleblock.phtml:

Hello, this is a sample block in a Hyva child theme MyCompany_SampleModule module!

Why?

The Hyvä compat module fallback mechanism follows this sequence:

1. Checks in the Hyvä child theme under the original module path (MyCompany_SampleModule::sampleblock.phtml).
2. If not found, checks in the Hyvä child theme under the Hyvä-compatible module path (Hyva_MyCompanySampleModule::sampleblock.phtml).
3. If still not found, checks in the Hyvä compatibility module (Hyva_MyCompanySampleModule::sampleblock.phtml).
4. Finally, if none are found, checks in the original module (MyCompany_SampleModule::sampleblock.phtml).

For example, if you delete the template file MyCompany_SampleModule::sampleblock.phtml from the Hyvä child theme, the text of the template file Hyva_MyCompanySampleModule::sampleblock.phtml will be displayed:

Hello, this is a sample block in a Hyva child theme Hyva_MyCompanySampleModule module!

Step 4: Best Practice

In standard Magento development, it’s common practice to override template files in the child theme under the same module path as the original template.

However, in the Hyvä theme, it’s not recommended to override templates under the Hyvä-compatible module path (Hyva_MyCompanySampleModule) within the Hyvä child theme.

Always override templates under the original module path (MyCompany_SampleModule) instead of the Hyvä-compatible module path (Hyva_MyCompanySampleModule).

If a custom template file is added exclusively in the Hyvä-compatible module (one that doesn’t exist in the original module), you should place the template in the Hyvä-compatible module path within your Hyvä child theme.