In this article, we will talk about UI Components and their configuration. This topic is quite extensive and it is impossible to cover it all at once. That’s why I will touch upon general points and show you the direction in which to move for a deeper understanding of the topic.
What is Magento 2 UI Component
UI Components enable the interaction between the JavaScript components and the server. A UI Component is responsible for rendering a certain fragment of the page and the subsequent interaction with it. As a rule, this page fragment contains UI elements, such as forms, buttons, tables, dialogs and so on. Thanks to the UI Component, user interaction with these elements gets much simpler.
Let’s look at a specific example for a better understanding. Imagine you have filled out all the necessary fields (Name, Email, etc.) while placing an order on the site, and then suddenly remembered that you have a discount coupon code. Without UI Components, you would have to go back one step to the shopping cart and apply the coupon code there, then go back to the checkout and re-enter your data. But using UI Components allows you to apply the coupon code directly at the checkout, after which only a part of the page that is re-rendered and you do not have to re-enter your data. This is way more convenient.
Each UI Component consists of the following combination of elements:
- XML declaration (defines the internal structure of the component and its configuration parameters);
- JavaScript class ( it’s inherited from one of the basic classes of the Magento JavaScript framework UI components, such as UIElement, UIClass or UICollection);
- Related templates (using KnockoutJS bindings, UI Components can be bound to the HTML templates).
UI Components can be used for both the admin panel and site front end.
How to specify configuration options on a UI Component widget in JSON and in Layout XML
Before talking about UI Component configuration parameters, it will be useful to get the general idea of rendering these components in the Magento system.
Initially, the server receives a request for a page. While generating a response, the system receives the UI Component configuration as .xml declaration files. Next, this configuration is modified by .php modifiers. After that, the combined configuration is packed into the JSON format and is added to the HTTP response code from the server.
As you can see, the UI Component configuration is initially specified in the .xml declaration.
An example of this configuration can be found in the file “app/code/Magento/Catalog/view/frontend/layout/default.xml”:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
<!-- --> <arguments> <argument name=”jsLayout” xsi:type=”array”> <item name="components" xsi:type="array"> <item name="compareProducts" xsi:type="array"> <item name="component" xsi:type="string">Magento_Catalog/js/view/compare-products</item> </item> </item> </argument> </arguments> <!-- --> |
Inside argument name = “jsLayout” we specify the data that needs to be output at a given location and set the configuration for the component (change the property values, etc.). In our example, this is a component with “compare products” in the left sidebar on the category page. We specified the path to the “Magento_Catalog/js/view/compare-products” file for item name=”component” and when rendering the page, the system will look for the component file “app/code/Magento/Catalog/view/frontend/web/js/view/compare-products.js”.
After rendering the page, the configuration of our component in the JSON format will look like this:
|
1 2 3 4 5 6 7 |
<script type="text/x-magento-init"> {"[data-role=compare-products-link]": {"Magento_Ui/js/core/app": { "components":{"compareProducts":{ "component":"Magento_Catalog\/js\/view\/compare-products" }} }}} </script> |
What configuration options are available on Magento 2 UI Components
In Magento 2 there are 2 types of UI Components — basic and secondary. There are currently two basic components — “Listing component” and “Form component”. All other components are secondary and are inherited from the basic ones.
Each UI Component has defaults properties. The parents of this component (the basic UI Components) also have the defaults properties. The values of all these properties can be overridden in their configuration (as I’ve described above).
After rendering the page, the property values from the resulting JSON overwrite the values for the defaults properties. After that, the resulting properties become the properties of the first level of the newly created instance of the UI Component, and the original values of the defaults properties are deleted.
A complete list of properties for each UI Component can be found on the official Magento site.
How to specify the ko template for a Magento 2 UI Component
Virtually every UI Component contains a “template” property that sets a template for it. The value of this property is formed as follows:
{Module_Name}/{Path}/{Template_Name}, where
- {Module_Name} is the name of the module, containing a template;
- {Path} is the path to the template file, relative to the view/<area>web/template folder in the module’s folder (if the template is located directly in this folder, then there will be no Path in the template address);
- {Template_Name} is the name of the template without the .html suffix.
For example, there is such a fragment of the UI Component configuration code in the app/code/Magento/Checkout/view/frontend/layout/checkout_index_index.xml file:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
<!-- --> <arguments> <argument name="jsLayout" xsi:type="array"> <item name="components" xsi:type="array"> <item name="checkout" xsi:type="array"> <item name="component" xsi:type="string">uiComponent</item> <item name="config" xsi:type="array"> <item name="template" xsi:type="string">Magento_Checkout/onepage</item> </item> </item> </item> </argument> </arguments> <!-- --> |
Here the template, located at app/code/Magento/Checkout/view/frontend/web/template/onepage.html is connected in the following way:
<item name=”template” xsi:type=”string”>Magento_Checkout/onepage</item>
Respectively, Magento_Checkout is the name of the module containing the ko template and onepage is the name of the ko template without the .html suffix.
Since the template is located in the module’s root folder view/<area>web/template, the {Path} is absent.
Demonstrate an understanding of default.tracks
Magento 2 UI Component JS files can contain a special tracks object. In this object, you should place those UI Component properties that can be dynamically changed and changes of which we need to track. This object converts the properties placed in it to knockout-es5 observable (for more information about knockout-es5 observable read an article on knockoutjs.com).
Here is how it looks like:
|
1 2 3 4 5 6 7 8 9 10 11 |
<!-- --> defaults: { property1: 'value 1', property2: 'value 2', property3: 'value 3', tracks: { property2: true, property3: true } }, <!-- --> |
Now “property2” and “property3” will be tracked and when they change, the script from the JS file will start again.
In this article, I tried to outline the general terms of UI Component configuration in Magento 2. For a deeper understanding of this topic, I strongly recommend you to read the articles Configuration flow of UI components and Overview of UI components from Magento 2 Developer, since this topic is included into Magento 2 developer certification exam.
Partner With Us
Looking for a partner to grow your business? We are the right company to bring your webstore to success.
Talk to Andrey
