How to Theme Enhanced Checkout

Enhanced Checkout (EC) has several ways that it can be customized to fit the brand of your store. This takes place through field translation and applying custom CSS style overrides.

How to translate Enhanced Checkout fields

In order to update the field values in Enhanced Checkout (e.g. change “Click and Collect” to “In Store Pickup”), you will need to create and load a custom module to the Magento store.

To create a module, you need to complete the following high-level steps:

  1. Create the module folder.
  2. Create the etc/module.xml file.
  3. Create the registration.php file.
  4. Create the translation files and overwrite the translation object.
  5. Install the module and check that it is working

Create the module folder structure

Navigate to the root folder for the Magento store and create the app/code/ShipperHQ/Translation folder. From the command line you would run:

  1. cd to the root folder
  2. mkdir -p app/code/ShipperHQ/Translation/etc
  3. mkdir -p app/code/ShipperHQ/Translation/view/frontend/layout
  4. mkdir -p app/code/ShipperHQ/Translation/view/frontend/web/js

Create the etc/module.xml file

This translation module depends on Enhanced checkout being installed, so you will define that “soft dependency” here. To create the file use:

touch app/code/ShipperHQ/Translation/etc/module.xml

Then you will need to add the following to the file:

<?xml version="1.0" encoding="UTF-8"?>
<config xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <module name="ShipperHQ_Translation" setup_version="1.0.0">
        <sequence>
            <module name="ShipperHQ_Client"/>
            <module name="ShipperHQ_Server"/>
        </sequence>
    </module>
</config>

Create the registration.php file

To help Magento locate the module, you need to create the registration.php file. From the command line run:

touch app/code/ShipperHQ/Translation/registration.php

Then add:

<?php
\Magento\Framework\Component\ComponentRegistrar::register(
    \Magento\Framework\Component\ComponentRegistrar::MODULE,
    'ShipperHQ_Translation',
    __DIR__
);

Create the translation files and overwrite the translation object

The translation file is where you can update what will be displayed in Enhanced Checkout for your store. Create the file by running:

touch app/code/ShipperHQ/Translation/view/frontend/ec_translation.js

From there you can update the fields based on what you want to display by updating the global SHIPPERHQ_TRANSLATION variable. Below is an example ec_translation.js file.

window.SHIPPERHQ_TRANSLATION = {
    shq: {
        checkout: {
            addressPage: {
                fillAddressFirst:
                    "Please enter your shipping address to see shipping methods.",
                noShippingToYourAddress: "No shipping methods available",
            },
            shipping: {
                pickup: {
                    showAllLocations: "Show All Locations",
                    clickToShowAllLocations: "Click to show all locations",
                    showMap: "Show Map",
                    hideMap: "Hide Map",
                    change: "Change",
                },
                inStore: "Click & Collect",
                delivery: "Delivery",
            },
            summary: {
                deliversOn: "Delivers",
                pickupAt: "Pickup at",
            },
        },
    },
};

Important: Updating this file will overwrite all the field descriptions. Make sure that you have a value for any fields you want to display. To see what fields are responsible for what, go to the “Which fields can be modified?” section of the article.

Once you’ve created the JavaScript translation file, you will need to make sure it is linked to the page. First, create the layout by running:

touch app/code/ShipperHQ/Translation/view/frontend/layout/checkout_index_index.xml

Then update the file by linking the translation file to the <head> of the page. Inside of checkout_index_index.xml add:

<page xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <head>
        <script src="ShipperHQ_Translation::js/ec-translation.js" />
    </head>
</page>

Install the module and check that it is working

All that’s left is to install the module and make sure it was added correctly. To install the module run:

php bin/magento setup:upgrade

Once the command finishes you should be able to see translations on your checkout page. To make sure the module installed correctly, you can check the config.php file by running:

grep ShipperHQ_Translation app/etc/config.php

Which fields can be modified?

FieldDescription
shq.checkout.addressPage.fillAddressFirstDisplays before the customer has entered an address and rates have not been fetched.
shq.checkout.addressPage.noShippingToYourAddressDisplays when there are no rates
shq.checkout.shipping.inStoreText inside button to display In Store Pickup options
shq.checkout.shipping.deliveryText inside button to display shipping methods
shq.checkout.shipping.pickup.showAllLocationsDisplays when in store pickup is enabled and there are multiple pickup locations. This is the button text.
shq.checkout.shipping.pickup.clickToShowAllLocationsDisplays when in store pickup is enabled and there are multiple pickup locations. This is the text that displays when the button is hovered.
shq.checkout.shipping.pickup.showMapDisplays when in store pickup is enabled and the map is hidden
shq.checkout.shipping.pickup.hideMapDisplays when in store pickup is enabled and the map is visible

How to apply custom styles to Enhanced Checkout

In order to apply custom styles to elements, you will need to upload a CSS file targeting the elements you would like override styles for.

Create a module

Create a module following the same steps mentioned above for creating an EC translation module. You can skip the steps for creating the JavaScript files.

After creating the module you should have the following files:

  • view/frontend/layout/checkout_index_index.xml
  • etc/module.xml
  • registration.php

Add your custom styles

To add your own styles, create a file called override.css in the web/css folder. First create the folder by running:

mkdir -p app/code/ShipperHQ/Translation/view/frontend/web/css

Then inside that folder, create a file to write your styles. To create a file called override.css run:

touch app/code/ShipperHQ/Translation/view/frontend/web/css/override.css

Link the file to page by adding it to checkout_index_index.xml. Your file should be similar to the following:

<page xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <head>
        <css type="text/css" src="ShipperHQ_Translation::css/override.css"/>
    </head>
</page>

If you are also overriding the Enhanced Checkout translation file, you can add it above or below the script tag.

Note: You can name the CSS override file anything as long as it matches what you include in checkout_index_index.xml.

You can target any elements of enhanced checkout and add your own styles inside override.css. Here is a simple example overriding the font and background color of the shipping methods section:

#shq-shipping-view {
    color: green !important;
}

#shq-shipping-view div.shpmt-cont {
    background-color: #bbb !important;
}

Install the module

Once you’ve added the CSS, you just need to install/update the module to see your changes. On the command line run:

php bin/magento setup:upgrade

What cannot be changed

Currently, not all aspects of Enhanced Checkout can be updated. Some of these areas include:

  • HTML structure
  • Data flow

Was this doc helpful?