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.