loki Documentation

Adding a quote field to the checkout

This playbook scenario goes through all steps to create a block. In this case, we are going to add a new field to the quote itself, called yireo_training_example.

Add a new database column to the quote

Create a file etc/db_schema.xml:

<?xml version="1.0"?>
<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Setup/Declaration/Schema/etc/schema.xsd">
    <table name="quote" resource="default">
        <column xsi:type="varchar" name="yireo_training_example" nullable="true" length="255" comment="Yireo Training Example"/>
    </table>
</schema>

Here, we are extending upon a core table quote. This is not best practice, because this could lead into issues when you are not using blue/green deployment and are adding this new column to an existing table with large numbers of rows. The alternative is to create an extension attribute, which is out-of-scope for this example tutorial. Or use blue/green deployment temporarily for such a change. For a new shop, this probably is no issue.

Also create a file etc/db_schema_whitelist.json:

{
  "quote": {
    "column": {
      "yireo_training_example": true
    }
  }
}

Run the database upgrade

bin/magento setup:upgrade

Confirm that the table quote has a new column yireo_training_example.

Add output to the checkout

Next, create a file view/frontend/layout/loki_checkout_block_customer.xml:

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:View/Layout:etc/page_configuration.xsd">
    <body>
        <referenceBlock name="loki-checkout.customer">
            <block
                name="loki-checkout.customer.yireo_training_example" as="yireo_training_example"
                template="Loki_FieldComponents::form/field.phtml">
                <arguments>
                    <argument name="field_label" xsi:type="string" translate="true">Yireo Example</argument>
                    <argument name="placeholder" xsi:type="string" translate="true">Enter some value</argument>
                </arguments>
            </block>
        </referenceBlock>
    </body>
</page>

Note that you do not need to create a PHTML template for this. You are reusing one from the Loki_FieldComponents module.

Finally, create a file etc/loki_components.xml:

<?xml version="1.0" encoding="UTF-8" ?>
<components xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Loki_Components:etc/loki_components.xsd">
    <component
        name="loki-checkout.customer.yireo_training_example"
        group="quoteFields"
    />
</components>

This XML file reuses definitions (viewModel, repository, context) from a group quoteFields. If those classes are sufficient, you don't need much else. You could also extend them with your own PHP classes. In that case, the etc/loki_components.xml entry needs to be updated as well.

Refresh the cache and voila!

bin/magento cache:flush

You should now see a new field in the checkout named Yireo Example. When a value is entered, an AJAX request will save the value into the quote table.

Where to go next?

  • See the documentation on Loki Field Components to learn what else you can configure via the XML layout;

  • If you want to add validators, filters or extend upon the component itself, go for the docs on Loki Components;

  • This XML file reuses definitions (viewModel, repository, context) from a group quoteFields. If those classes are sufficient, you don't need much else. You could also extend them with your own PHP classes. In that case, the etc/loki_components.xml entry needs to be updated as well.

  • There is no need to turn this into an extension attribute. However, if you want this to work easily in other non-checkout-related features (adding the attribute to the order email, the invoice email, the backend, etc), it is probably handy. But out-of-scope here. But if you would go for this, make sure to create your own component repository class.

Last modified: October 10, 2025