Skip to content

The hyva_checkout.xml file

hyva_checkout.xml introduction

Hyvä Checkout is a framework for building, well, checkouts. There can be multiple checkout variants within one Magento instance, all configured using XML.

The name of the checkout configuration file is etc/hyva_checkout.xml.

The magento2-hyva-checkout module contains an etc/hyva_checkout.xml file with the checkout configurations included with Hyvä Checkout.

When a checkout page is requested, all the hyva_checkout.xml files from all modules and themes are merged into one data structure.
This structure defines all available checkouts, and also defines which steps to display under what circumstances.

The actual contents of the checkout steps are configured using layout XML.

Every Hyvä checkout configuration has a name, so it can be referred to from other configuration files, and it also has a human-readable label.
A checkout configuration can be assigned to a Magento Website or Store View in the system configuration at Hyva Themes > Checkout > General > Checkout.

The hyva_checkout.xsd schema

If you are interested such things, you can find the schema for hyva_checkout.xml files in the hyva-themes/magento2-hyva-checkout module at src/etc/hyva_checkout.xsd.

Checkout config merging

All etc/hyva_checkout.xml files from all active modules are merged to produce the final checkout configuration.

In addition to hyva_checkout.xml files in modules, themes may also extend the Hyvä Checkout configuration with an etc/hyva_checkout.xml file.

A theme hyva_checkout.xml file is only merged if the theme is used for the current store view.

The merging works similar to the Magento theme fallback. For the checkout the merge order is:

  1. all module hyva_checkout.xml files in module load order
  2. the base theme hyva_checkout.xml
  3. the hyva_checkout.xml files from other themes in the theme fallback
  4. the current theme hyva_checkout.xml

Files that are merged later have a higher priority and can override values from previously merged files.

Contents of hyva_checkout.xml

A hyva_checkout.xml files contain one or more checkout configurations.

Each checkout configuration consists of one or more steps.
During the checkout, a visitor has to go through all the steps to complete the checkout.

The hyva_checkout.xml file defines the order of steps and which steps are visible.
For example, a login step should only be visible if a visitor is not logged in yet.

On the front end, each step contains one or more checkout components.
Components are sections of HTML, for example, a login form, an address list, or a quote summary.
The components for a checkout step are configured using layout XML, not the hyva_checkout.xml.

Components can be shared between steps or can be visible on a single step only.

Annotated hyva_checkout.xml configuration

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:module:Hyva_Checkout:etc/hyva_checkout.xsd"
>
    <!-- name: The name is used to refer to the checkout configuration in other hyva_checkout.xml files and to construct layout XML handles -->
    <!-- label: Used in the checkout selection dropdown in the admin configuration -->
    <!-- layout: (optional) Determines the default structure of a checkout step into which components can be arranged -->
    <!-- parent: (optional) The name of the parent checkout configuration -->
    <!-- visible: (optional) Determines if the checkout needs to be shown in the checkout selection dropdown -->
    <checkout name="my-checkout" label="My Checkout" layout="2columns">

        <!-- name: The step name is used to refer to the step in other hyva_checkout.xml files and is used to construct layout XML handles -->
        <!-- label: The step label is displayed in the checkout step navigation on the front end. It is passed through the __() function -->
        <!-- route: (optional) The attribute is used as part of the URL during the checkout. It can be used to create deep links to specific steps, and defaults to the step name -->
        <!-- remove: (optional) Remove a step from the checkout that was declared in a different hyva_checkout.xml file -->
        <!-- ifconfig: (optional) Only use the step if the given system config path has a truthy value (can be negated with ! as the first character of the attribute value) -->
        <!-- before: (optional) The name of another step before which this step should be placed -->
        <!-- after: (optional) The name of another step after which this step should be placed -->
        <!-- layout: (optional) Determine the structure of the checkout step into which components can be arranged -->
        <!-- clone: (optional) Replicate a step from another checkout by referencing it with a dotted path: {checkout_name}.{step_name} (since: 1.1.17) -->
        <step name="login" label="Customer Login" route="login" layout="1column">

            <!-- name: Used to refer to the condition from other hyva_checkout.xml files -->
            <!-- if: (optional) A condition class name (1) or identifier string (2) of a step condition -->
            <!-- if: (1) The name of a class implementing Hyva\Checkout\Model\CustomConditionInterface -->
            <!-- if: (2) A condition identifier string that is mapped to a class name (in frontend/di.xml as an argument to Hyva\Checkout\Model\CustomConditionFactory) -->
            <!-- remove: (optional) Remove a condition that was declared in a different hyva_checkout.xml -->
            <!-- before: (optional) Evaluate this condition before the condition with the given name -->
            <!-- after: (optional) Evaluate this condition after the condition with the given name -->
            <!-- method: (optional) The name of the method on the condition class to call when determining if the condition is true or false -->
            <condition name="is_customer_required" if="is_customer_required" />
            <!-- Should there be multiple conditions, a step will be shown if all are true -->
            <condition name="is_guest" if="is_guest"/>

            <!-- handle: Layout XML handle to include in the step -->
            <!-- if: (optional) Only include the handle if the "if" condition is truthy. Can be a class or condition identifier as for <condition> above -->
            <!-- method: (optional) Mark an alternative class method name other than the default 'validate' -->
            <!-- processor: (optional) An advanced option to mark a different layout handle processor -->
            <!-- remove: (optional) Will remove the handle from the step -->
            <update handle="my_virtual_quote_layout" if="is_virtual"/>
        </step>
    </checkout>
</config>