Skip to content

The hyva_checkout.xml file

hyva_checkout.xml introduction

Hyvä Checkout uses the hyva_checkout.xml configuration file to define checkout variants and their step sequences. This XML-based framework allows multiple checkout configurations within a single Magento instance, each customized for different store views or business requirements.

The checkout configuration file must be named etc/hyva_checkout.xml and can be placed in both modules and themes. When a checkout page is requested, Magento merges all hyva_checkout.xml files from active modules and themes into a unified configuration structure. This merged structure defines all available checkouts and determines which steps display under specific conditions.

Every Hyvä checkout configuration requires a unique name (used for references in other configuration files and layout handles) and a human-readable label (displayed in the admin configuration). Checkout configurations can be assigned to specific Magento Websites or Store Views via system configuration at Hyva Themes > Checkout > General > Checkout.

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

The hyva_checkout.xsd schema

The XML schema for hyva_checkout.xml files is located in the hyva-themes/magento2-hyva-checkout module at src/etc/hyva_checkout.xsd. This schema defines all valid elements, attributes, and their relationships.

The actual contents of checkout steps (components like login forms, address lists, and quote summaries) are configured using layout XML, not in the hyva_checkout.xml file. The hyva_checkout.xml file controls step order and visibility, while layout XML controls what appears within each step.

Checkout config merging

All etc/hyva_checkout.xml files from active modules and themes are merged to produce the final checkout configuration. The merging process follows a specific priority order similar to Magento's theme fallback system.

Theme hyva_checkout.xml files are only merged if the theme is active for the current store view. This allows theme-specific checkout customizations without affecting other store views.

The merge order determines priority, with later files overriding values from earlier files:

  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 chain
  4. The current theme hyva_checkout.xml

Files merged later have higher priority and can override configurations from previously merged files.

Contents of hyva_checkout.xml

A hyva_checkout.xml file contains one or more checkout configurations. Each checkout configuration consists of one or more steps that visitors must complete during checkout.

The hyva_checkout.xml file defines the order of steps and their visibility conditions. For example, a login step should only be visible if a visitor is not yet authenticated. These visibility rules are controlled through step conditions.

On the front end, each checkout step contains one or more checkout components. Components are sections of HTML content such as login forms, address lists, or quote summaries. The components for a checkout step are configured using layout XML, not the hyva_checkout.xml file.

Components can be shared between multiple steps or restricted to a single step, depending on your configuration.

Annotated hyva_checkout.xml configuration

The following complete example demonstrates all available elements and attributes in a Hyvä Checkout XML configuration file. This annotated example shows the XML structure used to define checkout configurations, steps, conditions, and layout handles.

<?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>