Changing the grid of field blocks

This tutorial extends from the previous one, which explained the $css() utility.

The (billing and/or shippping) address form is using CSS grids (of 12 columns) to put all fields in the right place. Each field is a Magento block (so, a <block> within the XML layout). And because the outer <div> HTML element (as found within the PHTML template for each field, like form/field.phtml) is using the $css() utility, this can be used to style each field.

Changing the grid (the ugly way)

For instance, the prefix field can be given a column span 2 in the 12 column grid system:

<?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-step.shipping-address.prefix">
            <arguments>
                <argument name="css_classes" xsi:type="array">
                    <item name="block" xsi:type="array">
                        <item name="grid" xsi:type="string">col-span-2</item>
                    </item>
                </argument>
            </arguments>
        </referenceBlock>
    </body>
</page>

Likewise, by using the XML layout <move/> directive, you can move each field in the right position.

However, this becomes pretty cumbersome if you need to do this for all fields. There is a better way instead.

Using the etc/loki_checkout.xml configuration file

The module Yireo_LokiCheckout ships with a file etc/loki_checkout.xml which configures a sorting order and CSS grid classes. This looks similar to the following:

<?xml version="1.0" encoding="UTF-8" ?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Yireo_LokiCheckout:etc/loki_checkout.xsd">
    <grid_layout name="default_grid">
        <block alias="prefix" sortOrder="1" gridClass="col-span-6"/>
        <block alias="firstname" sortOrder="2" gridClass="col-span-6"/>
        <block alias="middlename" sortOrder="3" gridClass="col-span-6"/>
        ...
    </grid_layout>
</config>

This XML configuration is used by a ViewModel Yireo\LokiCheckout\Util\Block\GridBlock to adjust child blocks identified by their XML layout block alias (<block name="..." as="prefix">). For example, the PHTML template checkout/billing/address-form.phtml makes use of this:

/** @var \Yireo\LokiCheckout\Factory\ViewModelFactory $viewModelFactory */
/** @var \Yireo\LokiCheckout\Util\Block\GridBlock $gridBlock */
$gridBlock = $viewModelFactory->create(GridBlock::class);

And:

<?php foreach ($gridBlock->getChildren($block) as $childBlock): ?>
    <?= $childBlock->toHtml() ?>
<?php endforeach; ?>

Different grid layouts

The default grid layout is called default_grid, but other grid layouts can be created as well. For instance, the Yireo_LokiCheckoutNl module introduces a grid layout called dutch_grid and the Yireo_LokiCheckoutPostcodeNl modules introduces a grid layout called postcode_nl_grid. Just search for any etc/loki_checkout.xml file in your system.

You can also add your own grid layout if you want by adding a etc/loki_checkout.xml to a custom Magento module:

<?xml version="1.0" encoding="UTF-8" ?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Yireo_LokiCheckout:etc/loki_checkout.xsd">
    <grid_layout name="custom_grid">
        ...
    </grid_layout>
</config>

The grid layout is applied to a certain form via the XML layout.

For instance, the layout file loki_checkout_block_billing_address.xml could look as follows:

<?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.billing-address.address-form">
            <arguments>
                <argument name="grid_layout" xsi:type="string">custom_grid</argument>
            </arguments>
        </referenceBlock>
    </body>
</page>

And similarly, the layout file loki_checkout_block_shipping_address.xml could look as follows:

<?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.address-form">
            <arguments>
                <argument name="grid_layout" xsi:type="string">custom_grid</argument>
            </arguments>
        </referenceBlock>
    </body>
</page>
Last modified: January 22, 2025