Adding a new shipping method

Out of the box, shipping methods that are registered in the Magento core automatically popup in the Loki Checkout as well. You don't need to do anything for this. However, it might be that things are not working perfectly yet by default or that you need more customization. This document outlines the possibilities.

A custom module is needed:

• When you want to add a custom logo for each shipping method;
• When you want to add a custom form within the checkout;
• When delivery dates need to be picked from a listing;
• When pickup locations need to be displayed on a map;
• ...

Let's talk instead of hack

With Loki Checkout, we aim for an easy integration of shipment methods, where the code of one solution is easily reused for another. Keep it simple stupid. However, if this does not apply to your own customization, do not hack the code randomly to get things working.

Instead, get in touch so we can head for the best technical solution with the lowest technical debt.

Assumptions on this page

We assume that there is already an existing Magento 2 extension available for the PSP of choice. And we assume that this extension has been installed already.

If not, a LokiCheckout module is definitely needed.

Building a LokiCheckout module

A LokiCheckout module is a Magento module that depends on LokiCheckout_Core (both via the module.xml file and as a composer dependency). Likewise, we recommend you to have a README.md and CHANGELOG.md (based on Keep a Changelog).

You could create a new Magento module in the way you see fit. Alternatively, you might want to create a new module based upon the LokiCheckout_EmptyShipment module. To use one module as a template for another new module, you could use our Yireo_ModuleDuplicator to rename sources quickly.

All specific shipment steps are outlined below anyway.

Adding a custom logo via an icon resolver

Within the shipment method selection panel of the checkout (template LokiCheckout_Core::checkout/shipping/shipping-methods.phtml), methods are shown with a radiobox and a label. This can be extended with a logo which is displayed via the PHTML template LokiCheckout_Core::checkout/shipping/shipping-methods/icon.phtml. Within this template, a ViewModel LokiCheckout\ViewModel\ShipmentMethodIcon is being used to determine the output of an icon image (literally, the HTML of that icon).

The ViewModel yet again makes use of an icon resolver logic to try to map the shipment method to a relevant icon. For this, first create a new class:

<?php declare(strict_types=1);

namespace Yireo\Example\Shipment\Icon;

use Magento\Framework\Module\Manager as ModuleManager;
use LokiCheckout\Shipment\Icon\IconResolverContext;
use LokiCheckout\Shipment\Icon\IconResolverInterface;

class IconResolver implements IconResolverInterface
{
    public function resolve(IconResolverContext $iconResolverContext): false|string
    {
        return '<img src="foobar.png" />';
    }
}

Your new class needs to be registered with the LokiCheckout mechanism by adding a etc/frontend/di.xml file that adds your class to the constructor argument iconResolvers of the class LokiCheckout\Shipment\Icon\IconResolverListing:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="LokiCheckout\Shipment\Icon\IconResolverListing">
        <arguments>
            <argument name="iconResolvers" xsi:type="array">
                <item name="example" xsi:type="object">Yireo\Example\Shipment\Icon\IconResolver</item>
            </argument>
        </arguments>
    </type>
</config>

Common icon patterns

In the example above, a simple image foobar.png is returned. Obviously, you'll want to return the actual static content URL for this image. You can do that for instance via the method Magento\Framework\View\Element\AbstractBlockgetViewFileUrl() (by injecting Magento\Framework\View\Element\Template into your resolver class) - a bit ugly but it works nicely.

When working with image URLs, you might want to take a look at the ViewModel class Loki\Field\ViewModel\ImageOutput.

In the case of an SVG, it might be better to output the SVG directly (bypassing an <img> tag):

$iconFilePath = $iconResolverContext->getIconPath(
    'Yireo_Example',
    'view/frontend/web/images/example.svg'
);
        
return $iconResolverContext->getIconOutput($iconFilePath, 'svg');

Disable all logos

If you want to disable all logos for any shipment method, use the following in a di.xml file:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="LokiCheckout\Core\ViewModel\ShipmentMethodIcon">
        <arguments>
            <item name="enabled" xsi:type="boolean">false</item>
        </arguments>
    </type>
</config>

Adding a custom form

The shipment templates also allow for child templates to be added for the purpose of forms and additional things (like scripts). In this example, we'll use a custom shipment method with code foobar:

• Block name loki.checkout.shipping.methods.foobar.form
• Block name loki.checkout.shipping.methods.foobar.additional

These blocks do not exist yet, but you can easily add them yourselves. For instance, with a XML layout file loki_checkout_block_shipping_methods.xml a block for the form can be created at the global level 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>
        <block
            name="loki.checkout.shipping.methods.foobar.form"
            template="Yireo_Example::method/foobar.phtml"/>
    </body>
</page>

In this case, you can see that the block is just a plain PHTML template. How you want to build a HTML form in the PHTML template and link this to the PHTML template, is up to you. This could be custom logic, for instance a complete Loki Component.

A simple component Adding a `ComponentRepository` JavaScript compatibility

Delivery options and pickup locations

A lot of shipping methods offer delivery options and pickup locations. Reusing logic between modules is therefore a proper thing to do. With the LokiCheckout, various PHTML templates can be reused within a shipment logic:

• LokiCheckout_Core::checkout/shipping/shipping-method/locations.phtml and child templates
• LokiCheckout_Core::checkout/shipping/shipping-method/delivery-dates.phtml and child templates

These templates rely upon arrays of value objects to be passed via a parent block:

• Loki\Components\Location\Location[] in the case of locations
• \LokiCheckout\Shipment\DeliveryDate[] in the case of delivery dates and timeframes

The location logic also supports displaying pickup locations on a map (based on LokiMapComponents).

Pickup locations in a dropdown or map

Some shipping methods render their pickup locations via the template LokiCheckout_ShippingMaps::checkout/shipping/methods/pickup-location.phtml. This template offers some flexibility to show or hide its subelements. The select title could be toggled with a property hide_select_title, the select box itself with hide_select and the map with hide_map.

For example, the following hides the select box, keeping the map:

<referenceBlock name="loki-checkout.shipping.methods.lokisimpleshipping_lokisimpleshipping.form">
	<arguments>
        <argument name="hide_select" xsi:type="boolean">true</argument>
    </arguments>
</referenceBlock>

Note that in this case, the form of lokisimpleshipping_lokisimpleshipping is targetted. But this applies to any shipping method to the same template (like instore_pickup and amstorepickup_amstorepickup):

<referenceBlock name="loki-checkout.shipping.methods.amstorepickup_amstorepickup.form">
	<arguments>
        <argument name="hide_map" xsi:type="boolean">true</argument>
    </arguments>
</referenceBlock>

The template also calls the child aliases before, middle and after. This can be used to render the current value, for instance like this:

<referenceBlock name="loki-checkout.shipping.methods.lokisimpleshipping_lokisimpleshipping.form">
    <block
    	name="loki-checkout.shipping.methods.lokisimpleshipping_lokisimpleshipping.form.preview"
        as="after"
        template="LokiCheckout_SimpleShipping::sidebar/preview/shipping_details/selected-store.phtml"
    />
</referenceBlock>

Cleaning up

When your shipping method is selected, it might save further information in the quote. If another method is selected instead, you will need to clean up this information again. To do this, there is a ready-made event loki_checkout_shipping_method_update that allows you to hook into this:

File etc/frontend/events.xml:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Event/etc/events.xsd"
>
    <event name="loki_checkout_shipping_method_update">
        <observer name="LokiCheckout_Example::cleanupQuote" instance="LokiCheckout\Example\Observer\CleanupQuote"/>
    </event>
</config>

Class LokiCheckout\Example\Observer\CleanupQuote:

<?php declare(strict_types=1);

namespace LokiCheckout\Example\Observer;

use Magento\Framework\Event\Observer;
use Magento\Framework\Event\ObserverInterface;

class CleanupQuote implements ObserverInterface
{
    public function execute(Observer $observer)
    {
        $method = $observer->getMethod();
        if (str_starts_with($method, 'example_')) {
            return;
        }

        // @todo
    }
}