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 Yireo_LokiCheckout (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 Yireo_LokiCheckoutEmptyShipment 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 Yireo_LokiCheckout::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 Yireo_LokiCheckout::checkout/shipping/shipping-methods/icon.phtml. Within this template, a ViewModel Yireo\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 Yireo\LokiCheckout\Shipment\Icon\IconResolverContext;
use Yireo\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 Yireo\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="Yireo\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 Yireo\LokiFieldComponents\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');

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.shipping-methods.foobar.form
• Block name loki.checkout.shipping.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.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:

• Yireo_LokiCheckout::checkout/shipping/shipping-method/locations.phtml and child templates
• Yireo_LokiCheckout::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:

• Yireo\LokiComponents\Location\Location[] in the case of locations
• \Yireo\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).