How to use Magento 2 UI components in modules and solutions [Part 1]

Today we will focus on the latest Magento 2 functionality that opens numerous opportunities for creating user-friendly UI. That is UI components. This is a tutorial for Magento 2. Without further ado, let’s start with the value of UI components for Magento 2 developers.

DO YOU NEED HELP WITH CUSTOM DEVELOPMENT?LEAVE YOUR EMAIL AND WE’LL CONTACT YOU TO DISCUSS HOW WE CAN BE USEFUL.

Leave this field empty if you're human:

The basics of Magento 2 UI components

The UI component is a Magento 2 innovation designed for rendering UI elements on the screen. They enable a connection between the visual element of the UI and the processing of related data that users submitted. UI components, in essence, make it much easier for Magento 2 admins to use UI components on module grid as well as bring a couple of other benefits, such as:

Simplified layout.xml for the backend part of Magento 2;

Ability to merge HTML and JavaScript items and use this compound element as a JavaScript code;

Ability to create sophisticated UI components using basic ones;

Ability to use a single entity for rendering a UI element and working with it.

Default UI components in Magento 2

To understand how UI components are defined in Magento 2 out-of-the-box, let’s take the <listing>UI component example.

The <listing> tag is a standard UI component in Magento 2. By default, you can find the definitions of all standard UI components in the file vendor/magento/module-ui/view/base/ui_component/etc/definition.xml. For example, this is how the <listing> UI component is defined in thedefinition.xml:

Let’s look at this definition in detail.

First, the <listing> tag per se contains two attributes, those are class and component. The classattribute defines the PHP class that is responsible for processing data on the server as well as preparing data for the UI component <listing>. The componentattribute sets the js-module which is responsible for rendering the UI component in the browser.

To learn more about naming and defining js-modules in Magento 2, you can turn to the documentation on RequireJS module loader.

Second, the <argument> tag includes data that is used for initializing an object of the class Magento\Ui\Component\Listing or any other object of the class stated in the classattribute. Mind that the PHP class stated in the class attribute should be inherited from the parent class Magento\Ui\Component\AbstractComponent. This is how Magento\Ui\Component\Listing is realized:

The <argument> tag in the PHP code transforms into the dataset that is used in the class constructor Magento\Ui\Component\AbstractComponent.

Third, the template item defines the template which is used for rendering a UI component. In our case, the template is defined as templates/listing/default. This means that the following template is used:

By this template, Magento 2 override the info inside double braces {{…}} with a PHP method of the UI component. In this case, the system will call the method getName()from the class Magento\Ui\Component\Listing.

Now, to better understand how UI components work for real parts of the UI, let’s look at a Magento 2 standard Catalog module (Magento_Catalog).

UI components in Magento 2 Catalog Grid

Consider creating a product gridwith the Magento Catalog module. First, to be on the same page, let’s view the grid itself. For this, go to the Admin panel and open Catalog -> Product.

Now, let’s look how to code it.

UI components are added via layout.

If we open the vendor/magento/module-catalog/view/adminhtml/layout/catalog_product_index.xml file, we can activate the UI component with the following code:

The uiComponent tag is used to insert a UI component object (product_listing in our example) into the component tree. After we insert the UI component, we need to define it in the layout. For this, we go to the folder [path_to_module]/view/adminhtml/ui_component/ and create an .xml file named just like the UI component.

In the folder vendor/magento/module-catalog/view/adminhtml/ui_component/, you will find the product_listing.xml file, which contains the description of our UI component. This file has several sections, each of which describes particular aspects of the UI component. The description starts with the tag <argument> and looks as below:

Here the<argument> tag is also used to create a dataset for the class constructor Magento\Ui\Component\Listing. The Magento 2 provideritem, transferred in data, initiates dataSource. As you see, the provider value, product_listing.product_listing_data_source, comprises two parts. The former, product_listing, is the name of the UI component. The latter part, product_listing_data_source, is the name of the dataSource that is meant to process data on the server and make the UI component work with this data. dataSource is also defined in the file

The <dataSource>tag defines the component responsible for initializing the localStorage in the browser using a js-module. In our example, this is Magento_Ui/js/grid/provider with the following full path to the file:

The <dataSource> tagcontains the <dataProvider>subtag that defines the PHP class responsible for data processing on the server. In our case, this is Magento\Catalog\Ui\DataProvider\Product\ProductDataProvider. The PHP class set in <dataProvider> is inherited from the superclass Magento\Ui\DataProvider\AbstractDataProvider:

As you see, the <dataProvider> tag contains such settings asrequestFieldName and primaryFieldName.

The parameter primaryFieldName relates to the primary column of the database with which dataProvider works. The parameter requestFieldName enables the AJAX URL used by the grid.

As you can see, the <dataSource>tag is followed by the <listingToolbar>tag in the product_listing UI component.

The tag <listingToolbar> defines the element that contains Filters, Bookmarks, Column editor, Full-text search field, and Mass Actions. This is how these UI components look on the Magento 2 grid:

The <listingToolbar>tag contains sub-elements responsible for particular features of the grid. Let’s consider some examples:

The tag <sticky>locks the upper menu and makes it follow users’ scrolls (see below for an example);

The <columns>tagis responsible for rendering the grid itself so it contains a full list of columns to be rendered on the grid. Let’s examine some columns defined in this tag:

The <selectionsColumn> is the element that defines the Checkbox column that allows users to “select all”, “select all on page”, “deselect all”, or “deselect all on page”. This is how it looks like in the module.

As usual, this column goes first. Mind that the nameattributeshould have the idsvalue, and the value of the indexFieldshould match the primary column of the database that is used to create the collection for data transfer to the grid.

All the rest columns are added in a similar way, so let’s take the Thumbnail column as an example:

This is how Thumbnail is defined:

The <column> element defines the column itself. Theclass attribute defines the PHP class which processes the data and settings of this element. The second attribute, component, is responsible for rendering the<column> element via a js-module.

Bottom line

Today we explored UI components in Magento 2, reviewed how they work in a standard Catalog module, and learned to create components from scratch.

As you see, the UI component is a powerful means to create elements of the interface. The key benefit that UI components bring is the combination of HTML and JavaScript, which allows creating new components with whatever possible appearance and functions. While designing your own Magento 2 modules, you can make use of Magento 2 standard UI components or develop your own extended for particular purposes.

Feel free to leave comments and questions in the feed below. And stay tuned, as our overview of Magento 2 Sections is coming up!

Well, You didn’t talk about what actually inside the “listingToolbar” tag, I mean it have “filters” tag and “massaction” tag, inside those 2 tags, it have alot of thing that we need to know. That’s what i’m looking for when searching the ui-component. I mean “how the filter and the search work, where does it go, which controller i need to looking for ..”

Hi there, thanks for reading us!
You see it’ll be pretty difficult to answer your question from here, as we lack some important details. We have at least two ways out. You can either detail your question so that I can refer the matter to our technical specialists, or you can leave the question in a ticket on our Support page.