Every eCommerce Checkout Page is unique and different because they address a variety of requirements. Not all store owners/customers would need the same set of fields that the Magento platform offers. Here’s where Custom fields come into play. Creating custom fields enables businesses to add fields according to their business model as well as customers’ expectations. This article is about creating custom fields using the UI components in Magento 2, a new feature that allows store owners to add custom fields, per need, to the Checkout Page.
What are the UI components in Magento 2?
UI components in Magento 2 are a new approach that makes building user-interface components less cumbersome. For developers, this approach allows reusing components in different locations. Also, they have a few advantages over the old Magento 1’s user interface. The UI component approach:
- has a simplified layout, thus handling XML files is easy.
- pre-renders data in JSON format, thus more bound with Magento backend.
- uses AJAX in the case of updates.
That said, there are two types of basic components: Listing and Form. The scope of this article confines to create a custom field on the checkout page using the Form component in Magento 2.
The coding starts here…
Let’s imagine a scenario where a store owner wants to provide multiple shipping options to the customer – say free shipping to the customer’s address and also store or warehouse pick up. In the case of store/warehouse pickup, we’d want the customer to pick a preferred warehouse location, Name and Contact number of the person who’s going to take the delivery, and preferred delivery time. Thus, I would need three different custom options (a select option, input fields, and a date component) to save in quote and sales_order table as shipping method options.
You can download the entire module from the below GitHub repository:
Create a new module in the Magento and follow the steps populated below. You could go through the following link to know more about creating a new module: http://devdocs.magento.com/videos/fundamentals/create-a-new-module/
For instance, I have created a module with Dckap as Vendor name and CustomFields as the module name.
To create a custom option in the corresponding table, create InstallSchema.php in the path app/code/Dckap/CustomFields/Setup.
Input fields: (input_custom_shipping_field, date_custom_shipping_field, select_custom_shipping_field) of data type text.
Among several input fields available in the UI Component system, I have chosen Select, Text, and Date as custom fields. To choose your own input fields, you can refer the following Magento blog for a detailed know-how on UI components:
To populate the chosen custom fields on the checkout page, create a plugin for the process method, Magento\Checkout\Block\Checkout\LayoutProcessor in the path app/code/Dckap/CustomFields/Plugin/Checkout/LayoutProcessorPlugin.php
elementTmpl → the path to the .html template for the field type used.
component → the path to the .js component.
option → used to display the set of values for select option
template → the path to the .html field template under which the particular type of field is bound.
Declare the plugin Dckap\CustomFields\Plugin\Checkout\LayoutProcessorPlugin for the class Magento\Checkout\Block\Checkout\LayoutProcessor in your module’s di.xml.
To include the custom fields in shippingMethodItemTemplate, declare a region custom-shipping-method-fields under the section shippingAddress in the file path app/code/Dckap/CustomFields/view/frontend/layout/checkout_index_index.xml
Override the shipping-method-item.html in the path app/code/Dckap/CustomFields/view/frontend/web/template/shipping-address/
Here, I’m going to display the custom fields for the particular shipping method (say, freeshipping). To display other custom fields, use the region custom-shipping-method-fields that is declared as displayArea in checkout_index_index.xml file.
To validate the custom fields and display the custom-shipping-method-fields, using selected shipping method, override the shipping js component that is used for rendering the shipping method template in the path app/code/Dckap/CustomFields/view/frontend/web/js/view/shipping.js
customShippingMethodFields → the custom scope declared in LayoutProcessor while constructing the custom UI component fields.
To validate the custom fields, use the function validateCustomFieldsShipping from setShippingInformation so that they can be validated along with default shipping fields. The custom-shipping-method-fields can be displayed using the selected method observable.
Override the above shipping js component as a mixin in the file path app/code/Dckap/CustomFields/view/frontend/requirejs-config.js
Should you have followed closely and mimicked until Step 7, custom fields should be visible under the required shipping method. Once the fields are displayed, they can be saved in the quote table using a concept of extension attribute. Since we are going to apply the attributes in the shipping information, an extension attributes for \Magento\Checkout\Api\Data\ShippingInformationInterface can be created in the file path app/code/Dckap/CustomFields/etc/extension_attributes.xml.
To include the extension attributes in the shipping information, override the Magento_Checkout/js/model/shipping-save-processor/default Component in requirejs-config.js
The custom option fields can be set in extension_attributes in the address information payload in the file app/code/Dckap/CustomFields/view/frontend/web/js/shipping-save-processor.js
This payload is set under the shipping address information, while the next step of the checkout process is continued.
On clicking the next button of the shipping step, the custom shipping method fields will be validated along with the other default shipping information in the shipping js component.
The extended attributes are created for \Magento\Checkout\Api\Data\ShippingInformationInterface for which the implementation class used is Magento\Checkout\Model\ShippingInformationManagement. The Extension attributes are available in address information payload and can be saved in quote table using a plugin before the method saveAddressInformation of the implementation class. Create a plugin in app/code/Dckap/CustomFields/Plugin/Quote/SaveToQuote.php
Declare the plugin Dckap\CustomFields\Plugin\Quote\SaveToQuote for the class Magento\Checkout\Model\ShippingInformationManagement in di.xml
Once the extension attribute is available in the quote table, we can save the Custom fields in the sales_order table. The observer is declared for sales_model_service_quote_submit_before event so that the custom fields are saved while placing an order.
Declare the observer Dckap\CustomFields\Observer\SaveCustomFieldsInOrder in app/code/Dckap/CustomFields/etc/events.xml to save the extension attributes.
Create an observer SaveCustomFieldsInOrder.php in the path app/code/Dckap/CustomFields/Observer/ and save the extension attribute values in the sales_order table.
Once the order is placed, the custom shipping method fields will be saved in the sales order table. The values can be shown in the order details using these custom fields values.
I hope the article turned out to be useful in creating custom fields in the Checkout page using UI components in Magento 2. Please feel free to drop us a line, should you have any queries or feedback. We’re looking forward to addressing more topics in the future.