Skip to content

The hyva_checkout.xml file

Can I join the Hyvä Checkout Beta?

Would you like to join the list of Beta participants?
Existing Hyvä customers and service integrators can contact us in Slack or email

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 checkout-default module contains an etc/hyva_checkout.xml file with the checkout configurations included with Hyvä Checkout out of the box.

When a checkout page is requested, all the hyva_checkout.xml files 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.

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/checkout-core 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 any 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=""
    <!-- urn:magento:module:Hyva_CheckoutDefault: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 -->
    <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 -->
        <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\CheckoutCore\Model\CustomConditionInterface -->
            <!-- if: (2) A condition identifier string that a class name (in frontend/di.xml as an argument to Hyva\CheckoutCore\Model\CustomConditionFactory) -->
            <!-- remove: (optional) Remove a step 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 -->
            <update handle="my_virtual_quote_layout" if="is_virtual"/>