Magento 2: how to make Checkout modifications

checkout modifications
Checkout is one of the most complex elements of Magento 2 in terms of code and making modifications. Sooner or later any developer working with Magento 2 faces the need to alter this store section. To gain full insight into how Checkout works we need to learn the Knockout.js (especially HTML template processing) and how Magento 2 initialises JS modules.

Checkout rendering in Magento 2

The checkout process page in Magento 2 comprises a range of Knockout.js components, whose configuration and loading methods are defined in a single XML file (depending on how the Magento 2 instance was installed – /app/code/Magento/Checkout/view/frontend/layout/checkout_index_index.xml or /vendor/magento/module-checkout/view/frontend/layout/checkout_index_index.xml). The definition included in this file is one abstraction level higher than the standard JS module initialization:

<script type="text/x-magento-init">
(...)
</script>

The XML file is converted to JSON and submitted to the core JS module responsible for loading all the components defined in the XML file.

Structure of checkout_index_index.xml 

The Checkout configuration file may seem complicated at first (it has more than 500 lines), but once we recognize its components it becomes much easier to read. The most important node is the one which includes the configuration of all elements:

<item name="components" xsi:type="array">
(...)
</item>

This section comprises a series of embedded component definitions. The definition of a single component has the following structure:

<item name="(...)" xsi:type="array">
  <item name="sortOrder" xsi:type="string">(...)</item>
  <item name="component" xsi:type="string">(...)</item>
  <item name="displayArea" xsi:type="string">(...)</item>
  <item name="children" xsi:type="array">
    (...)
  </item>
  <item name="config" xsi:type="array">
    (...)
  </item>	
</item>

The name attribute in the containing block includes the section name for the component. The following elements can be found inside:

– the parameter specifying the order of rendering
– the alias or path to the module from Require.js
– the area to render the component
– the list of embedded components
– configuration parameters

 Adding a new element on the checkout process page

 Checkout, like most Magento 2 elements, is a module. According to Magento 2 rules, any module can be extended in two ways: in the template catalogue, or in the catalogue of another module. We can use the example of the module that integrates Poczta Polska services with Magento 2 [INSERT THE STORE LINK] to show how we can add a map with pickup points to the shipping method section in the checkout process.

First look inside the checkout_index_index.xml file to locate the component responsible for displaying shipping options. This location is defined in the following tree path: components > checkout > steps > shipping-step > shippingAddress. After locating it, add our new component in the children section; it will inherit its properties from the default uiComponent:

<item name="poczta-polska-in-point" xsi:type="array">
  <item name="component" xsi:type="string">uiComponent</item>
  <item name="displayArea" xsi:type="string">shippingAdditional</item>
  <item name="children" xsi:type="array">
    <item name="poczta-polska-in-point-block" xsi:type="array">
      <item name="component" xsi:type="string">Unity_PocztaPolskaInPoint/js/view/poczta-polska-in-point</item>
    </item>
  </item>
</item>

Besides the map itself, we also need to specify where the selected pickup point will be displayed. This is placed in: components > checkout > sidebar > shipping-information:

<item name="sidebar" xsi:type="array">
<item name="children" xsi:type="array">
<item name="shipping-information" xsi:type="array">
<item name="component"
xsi:type="string">Unity_PocztaPolskaInPoint/js/view/shipping-information</item>
</item>
</item>
</item>

Unfortunately, when we add any element to the tree we also need to keep the default embedding scheme, which makes our checkout_index_index.xml file rather bulky. Here is the complete file in the module catalogue:

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" layout="checkout" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="content">                
            <referenceBlock name="checkout.root">
                <arguments>
                    <argument name="jsLayout" xsi:type="array">
                        <item name="components" xsi:type="array">
                            <item name="checkout" xsi:type="array">
                                <item name="children" xsi:type="array">
                                    <item name="steps" xsi:type="array">
                                        <item name="children" xsi:type="array">
                                            <item name="shipping-step" xsi:type="array">
                                                <item name="children" xsi:type="array">
                                                    <item name="shippingAddress" xsi:type="array">
                                                        <item name="component" xsi:type="string">Unity_PocztaPolskaInPoint/js/view/shipping</item>
                                                        <item name="children" xsi:type="array">
                                                            <item name="poczta-polska-in-point" xsi:type="array">
                                                                <item name="component" xsi:type="string">uiComponent</item>
                                                                <item name="displayArea" xsi:type="string">shippingAdditional</item>
                                                                <item name="children" xsi:type="array">
                                                                    <item name="poczta-polska-in-point-block" xsi:type="array">
                                                                        <item name="component" xsi:type="string">Unity_PocztaPolskaInPoint/js/view/poczta-polska-in-point</item>
                                                                    </item>
                                                                </item>
                                                            </item>
                                                        </item>
                                                    </item>
                                                </item>
                                            </item>
                                        </item>
                                    </item>
                                    <item name="sidebar" xsi:type="array">
                                        <item name="children" xsi:type="array">
                                            <item name="shipping-information" xsi:type="array">
                                                <item name="component" xsi:type="string">Unity_PocztaPolskaInPoint/js/view/shipping-information</item>
                                            </item>
                                        </item>
                                    </item>
                                </item>
                            </item>
                        </item>
                    </argument>                
                </arguments>        
            </referenceBlock>             
        </referenceContainer>
    </body>
</page>        

As a result of these changes, a map of the pickup points will be displayed on the checkout process page:

Summary

Understanding the shopping process can take much time for anyone who is not well versed with Magento 2, but this is necessary for our everyday work involving feature extension. Compared to Magento 1, Checkout is much better developed despite its complexity. From the technical point of view, its division into components offers many benefits and enables modifications without breaking the universally accepted patterns.

Front-end developer at Unity Group. Tomasz is in charge of visual aspects of our projects. Although he follows all the latest trends in web app development, he prefers proven industry standards over unrestricted experiments. With several years of experience, Tomasz has worked for clients, such as Royal Canin, Rovese, Toyota Nowakowski, Tubes International and Homla.

Fields marked with an * are required

UNITY GROUP NEWSLETTER

Subscribe and stay on top of the latest tech news and guides:

TELL US ABOUT YOUR PROJECT

Questions? Don't hesitate to drop us a line - we're here to help.

Fields marked with an * are required