With Luma and Hyvä, developers have become so grown to creating template overrides, that it is often the very first means to modify things. And this quickly leads to the burden of legacy: Whenever the original template is updated, the override needs to be checked for as well. Even worse, often the override is just made out of habit, instead of being the best solution. For instance, with Hyvä Themes, template overrides are often created just to modify a bunch of Tailwind classes. Often upgrades in Magento are seen as troublesome - and most of the time, this is due to template overrides.
With the Loki Checkout, we aim to do this different. We don't want template overrides of the Loki Checkout.
The very first point here is: Do not create a template override at first. Below there is an outline of various other solutions that the Loki Checkout ships with. And if this fails, first ask us - the creators of the Loki Checkout - to verify which solution is best. And then only, as a last resort, we maybe agree that a template override is the best solution. Or possibly, we quickly release a new version to allow for the change you need without template overrides.
Template overrides are a bad habit, if you come to know that there are other means of modifying things.
The Loki Checkout tries to use small PHTML templates that have only a single purpose. Often, larger components are chopped up into numerous templates. Some developers might not like this (and they might prefer troublesome upgrades instead), but if you use the right debugging tools (PHPStorm XDebug, MSP DevTools, Loki Checkout Debugger) then finding templates is easy.
This is one example of such a small PHTML template: The checkout/progressbar.phtml template which shows the progress in steps. Note that only the PHTML code is shown in this simplified example.
<nav
class="<?= $css('hidden md:block card rounded-lg relative') ?>"
aria-label="<?= $escaper->escapeHtmlAttr(__('Pagination')) ?>">
<?= $blockRenderer->html('loki-checkout.utils.loader-overlay') ?>
<ul class="<?= $css('flex items-center', 'list') ?>">
<?php foreach ($stepNavigator->getSteps() as $step): ?>
<?= $block->getChildBlock('step')->addData(['step' => $step])->toHtml() ?>
<?php endforeach; ?>
</ul>
</nav>
So, what would you like to modify?
CssClass utility instead!etc/loki_checkout.xml file!In short, we don't see a reason why you should need a template override.
CssClass utilityWe try to make sure that all HTML elements that could potentially have CSS classes, are rendered by using the CssClass utility (aka \Yireo\LokiCheckout\Util\Block\CssClass). This utility is added as template variable $css() to all PHTML templates of the Loki Checkout.
And it allows for the default Tailwind classes (like hidden md:block card rounded-lg relative in the example above) to be either extended or replaced via the XML layout. Thanks to this utility, you don't need to override templates just to replace CSS classes.
For instance, we can refer to the block loki-checkout.progressbar using the XML layout and append the CSS class pb-4 to the existing CSS classes of the nav element:
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:View/Layout:etc/page_configuration.xsd">
<body>
<referenceBlock name="loki-checkout.progressbar">
<arguments>
<argument name="css_classes" xsi:type="array">
<item name="block" xsi:type="array">
<item name="padding" xsi:type="string">pb-4</item>
</item>
</argument>
</arguments>
</referenceBlock>
</body>
</page>
If you don't like the CssClass utility, we will not be angry (just a tiny little bit disappointed). For instance, you can use Tailwind CSS its @apply instead:
.loki-checkout-progressbar {
@apply pb-4;
}
Every single block in the Loki Checkout is uniquely named, including child blocks without an original name.
While the CssClass util already makes use of the XML layout, there are many many other things that you can configure via the XML layout: Field types, input templates, placeholders, whether a field is required, field labels, filters, validators, targets, timeouts, etc. We'll do our best to document everything here.
The XML layout is mostly used whenever blocks (or components) are being displayed (together with ViewModel classes). However, there is also other logic that is dealt with in Loki-specific XML files:
etc/loki_components.xml - Declaration of Loki Components, including their filters, validators and targets;etc/loki_checkout.xml - Loki Checkout structure including steps, grid configuration and themes;With Loki Checkout, tons of features are supported out-of-the-box. This includes core configuration settings, editing the cart within the checkout, EU VAT support, support for various payment provider architectures (PSP redirects, vault, JS-based PSPs), address autocompletion (Postcode NL, and possibly in the future other engines). On top of this, other common settings are supported as well - selecting an account type (personal or corporate), payment method tiles, lazy loading specific components and much more. We are even testing things with configurations like swapping the billing & shipping step and a single address checkout (no difference between billing & shipping address).
In short, we build the Loki Checkout with even the more exotic scenarios in mind. This proofs the flexibility of the Loki Components architecture, but also guarantees that huge code rewrites are not needed anymore in the (near) future.
With the Loki Checkout, we are not aiming to take over the market. Instead, we are aiming at helping out a select group of professional agencies, skilled in Magento developnment and looking for a developer-friendly checkout. This means that we are eager to collaborate with our users. And this again means that we are rather looking for improving the core when needed, instead of having our users (you, developer) make expensive changes.
Template overrides, DI hacks, copy-and-pasting - they are signs of bad architecture. And we wish to prevent that from happening by working together with you.