Adding a custom block to a form

Each address form within the LokiCheckout is purely based on XML layout and blocks. To add a new (non-field) block is peanuts, as shown here.

For instance, to extend the shipping address with a new tempate example.phtml, create a new XML layout file loki_checkout_block_shipping_address.xml with the following contents:

<?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.shipping.address.form">
            <block
                name="loki-checkout-example.shipping.address.example" as="example"
                template="YireoTraining_Example::example.phtml"/>
        </referenceBlock>
    </body>
</page>

It is a good standard to name your block in an unique way like shown here (name="loki-checkout-example.shipping.address.example"). The alias (as="example"), however, could be seen as mandatory. In the tutorial Ordering blocks within a form, you can find how blocks within an address form are sorted. The alias is required to make sure your block can be positioned in the right way.

Next, a template file example.phtml could be as simple as the following:

<div>Hello World</div>

Note that the div does not contain classes. And because of this, it could look very ugly within the grid layout of a form. To fix this, you would need to add a TailwindCSS col-span-* class. A better version of your template therefore looks like the following:

<?php
declare(strict_types=1);

use Magento\Framework\View\Element\Template;
use Yireo\LokiComponents\Util\Block\CssClass;

/** @var Template $block */
/** @var CssClass $css */
?>
<div class="<?= $css('col-span-6') ?>">Hello World</div>

Adding more things to this block

Once this basic example is working, you can extend it at will. For instance, you could turn the block into a LokiComponent: Add a component to etc/loki_components.xml, define a Repository class and/or ViewModel class - done.

Last modified: April 1, 2025