Hire Magento 2 developers (up to 5 years exp, Magento 2 experience since beta release) Contact us now!


Magento2 admin UI Grid turtorial part 2: UI components

In a previous article – How to create Magento 2 UI Grid part 1 we were talking about extending the new admin panel grid with the help of a sample module.

Today, we will look deeper into Magento2 UI components, especially when you are using them for extending the Magento2 admin UI grid functionality.

UI components of Magento 2 admin

Ui Component – is ui_component / {entity_grid_listing} .xml file that provides information about the grid table and how data should be presented in it.

From the beginning, you should see the module-cms / view / adminhtml / ui_component / cms_block_listing.xml file, it looks relatively simple, but the lack of description of the documentation makes it rather hard that simple to understand how it works. Most ui grid pages have a similar structure of such a file: argument, dataSource, listingToolbar, columns.

But what do they actually do? Does the order of elements is important? What parameters can and should you pass? And most important, how does it all work?

UI Component – is a new feature of Magento 2, a mixture of knockout js and backend code. When you use the tag in your uiComponent layout Magento is said that it is necessary to process a file with the name in a certain way. In short, the Magento reads the component file, creates certain classes, in order to collect the options for the component, and ultimately prepares jsLayout configuration, which will be transferred to the front end and processed knockout js (will be created observables, viewModels, mapping view templates and so on) . Magento_Ui – extension is the one that provides the majority of ready to use components (viewModels), which you can use in your code. You can find them in the module-ui / view / base / web / js / *. The main configuration file is a module-ui / view / base / ui_component / etc / definition.xml, it contains a description and default options for all components, which you can use in your Ui Component. Any changes to this file (or your definition.xml file) will be applied to all extensions.

UI component configuration

Let us Test / UiGrid / view / adminhtml / ui_component / uigrid_grid_listing.xml. In order to make it easier to trace the structure I will enumerate the nested elements and highlight key locations.

Let’s start with the very first item that we see in the example from a previous article.

  1. <argument name=”data” xsi:type=”array”>.



<Item name = “js_config” xsi: type = “array”> contains information about the data provider on the front end, the provider name format must be {file_name} {file_name} _data_source.

<Item name = “spinner” xsi: type = “string”> contains a reference to the list of columns in the same file, the value must be identical to the name you specified for the columns tag. I recommend calling it {extension} _ {entity} _columns. If you do not set it or set it with the value different from true, then the Magento’s spinner will not stop even if the data is already loaded.

<Item name = “buttons” xsi: type = “array”> provides information about the buttons over the top.

Note that you can add other buttons with different classes, as shown below.

A button can be added not only via xml, but also through a separate class. Pay attention to the commented piece of code. The implementation of these classes, you will find within themselves.
2. <dataSource name=”uigrid_grid_listing_data_source”>

This section contains important information about the render URL, data provider class name of your collection, which provides data and so on. The attribute name must follow the following format: {file_name} _data_source and must be identical to the one you used previously.

You need to change only the following elements:

<Argument name = “name” xsi: type = “string”> must contain the name of your collection in di.xml,
<Argument name = “primaryFieldName” xsi: type = “string”>, <argument name = “requestFieldName” xsi: type = “string”>, <item name = “indexField” xsi: type = “string”> – entity id of your key in the database table.

Other attributes may be the same as in Example.

If the name is not set correctly, or the collection has not been described in di.xml you will see the following error

3. <listingToolbar name=”listing_top”>

This element contains a list of the top menu items, such as Filters, Bookmarks, Column editor, Full-text search field, Mass Actions, Pagination, and so on.

Keep in mind that you can fill out this XML in several extensions at the same time! Simply place ui_component file with the same name in the same or a base scope. The order of an element plays a big difference, so make sure that the order in which modules are loaded, and the elements are added to the ui_component. If <listingToolbar> will be loaded after the <columns>, you will get the following result:

Element’s name must be the same as indicated in an example.

3.1. <Item name = “sticky” xsi: type = “boolean”> optional, you can skip it. The default value «false». This setting provides the fastest access to the top menu during page scrolling, it will follow the scroll of until you scroll back to the very top.

3.2. <Bookmark name = “bookmarks”> is optional. It adds a button «Bookmark». If you add this element, Magento allows administrators to save the state of the columns and their position for use later. Each administrator your own list.

3.3. <ColumnsControls name = “columns_controls”> is optional. It adds a button «Columns». If you add this element, Magento allows administrators to add or remove some columns from your table grid.

3.4. <FilterSearch name = “fulltext“> is optional.  It adds full-text search field.

Magento developers have implemented a remarkable feature – search on any field in the database without writing any additional code! All you need to do is add a full-text index to 1 or more columns in the database. If your table has at least one full-text index the entered text will be searched for him. You can add indexes to your install scripts. Starting from MySQL 5.6.4 InnoDB tables support Full-text Index as well as MyISAM.

3.5. <Filters name = “listing_filters”> is optional. This element can contain additional filters for Micro and display. In the example you can see the <argument> and <filterSelect> elements.

Let’s start with the first one.

Sometimes you may need to change the template for a component or a specific type of filter (for example, change the behavior of text input in the filter list, or select element). The most frequent case in Magento 2 code is the replacement of a standard component, and select a template from the Dropdown to select ui-select filter status.

Please note that this change will affect all filters <item name = {type}> type.

Element «filterSelect» – this is an example of the standard filter change for store_id column. In general, almost all of the columns have their own filters (text, textRange, date, select, etc.), but in some cases you might need to override the behavior / display of such a filter for some columns. Available types: filterInput, filterRange, filterSelect and containerConfiguration (an error message will appear if you try to specify something else). The name must be identical to the name of the column, the filter that you want to override, otherwise the mapping will not work.

3.6. <Massaction name = “listing_massaction”> element is optional. It adds mass action Dropdown and a pop-up message if the user has not selected any row for an action.

Typically, this element looks like a normal Dropdown, but you can replace a component with a tree-like menu.

If you want to replace the defaulted message «You have not selected any items!» as shown above, you must pass the following parameters in massaction component bu simply inserting your message into the «noItemsMsg».

To add a new action in the Dropdown, take a look at the example below. This is an example of action «delete», but you can add others as well.

<action name = “delete”> – must have a unique name, as Magento merges elements by name.

<item name = “type”> – must be unique as well, otherwise Magento will show all of these options in the Dropdown, but they all will perform one and the same action as described in the first element of this type, because Magento caches configs by type. A good practice is to use the same name that you specified for the action.

<item name = “label”> – name of the option.

<item name = “url“> – URL actions that will be used for the processing of selected rows. It will be sent data to an array of selected / excluded elements, applied filters and applied full-text search terms. The difference between the transmitted parameters depends on the method of selecting items. If you press «select all» the item «excluded» contains «false». If you have chosen a few more items manually array «selected» will contain entity id of all selected records. To see an example of the implementation of «massDelete» action and how these parameters are processed look into a class Magento \ Cms \ Controller \ Adminhtml \ Block \ massDelete.

<item name = “confirm”> – an optional element. If specified, Magento will display a modal window to confirm the action with «Ok» or «Cancel» button. Title and Message can be changed as shown above.

Now let’s look how mass edit button works.

The main difference between them is the <item name = “callback”> element. It is optional. It’s parameters make it possible to edit multiple rows at once. In fact, it uses callback to the selected row.

That’s how changing grid looks like if the several lines are selected:

Such kind of editing will be available only those columns that have an «editor» attribute (further information below).

<item name = “provider”> – is the path to the component. The value must follow the following format {filename}. {Filename}. {Columns_element_name} _editor.

<item name = “target”> – is the name of the method in knockout js component, «editSelected» must be specified here.

Speaking about the options of the massaction Dropdown, as you saw earlier, there are 2 types of available options: conventional (select) and tree-like option. Unfortunately «select» component does not support the sub-menu, but tree-massactions do. To use this component you need to tell Magento use Magento_Ui / js / grid / tree-massactions component. «Action» element should already be familiar to you, so let’s take a look at minor changes in the following example:

<argument name = “actions” xsi: type = “array”> is optional. It contains an array of elements with names from 0 to N, but if the names do not follow the sequence of integers that knockout js (javascript) will throw an error.

<param name = “…”> … </ param> is optional. While all the information about the selected rows will be transferred to the body post request, these parameters will be passed as parameters and will depend only on the selected option (see. The example above). These parameters can be used with other massactions.

3.7. <paging name = “listing_paging” /> is an optional element. It adds pagination for your grid pages. If it has not been added, Magento will show all records on a single page and will not show the number of records found.

3.8. <exportButton name = “export_button” /> is an optional element. This component adds an export button with 2 options: export as csv, export as xml. You do not have to implement an additional logic for this feature to work. It generates a feed file containing only data available, according to the applied filters. File ignores the sort order and visibility of items, Magento always generates a file which includes all columns of the ui_component file. The columns will be in the order of their appearance in this file, completely ignoring the other sorting (including sorting attribute elements of the file). You can also add other formats to export, the detailed manual of doing that can be found at official documentation.

4. <columns name=”uigrid_grid_columns”>

This is the most interesting and important part to display the columns in the grid. This element contains a list of columns that should be available to the administrator.

<columns name = “uigrid_grid_columns”> – name of the element. It should be in the following format {extension} _ {entity} _columns and be identical to what you have registered in the <item name = “spinner” xsi: type = “string”> name_of_columns_element </ item>. Normally this tag has only an attribute «name», but can also contain a «class» like in the vendor / magento / module-catalog / view / adminhtml / ui_component / product_listing.xml.

<columns name = “product_columns” class = “Magento \ Catalog \ Ui \ Component \ Listing \ Columns”>
You will need to use the class element in columns only if you want to handle any kind of data, such as dynamical sorting, visibility of some columns or adding new columns dynamically.

In the next article, we will look deeper into Magento 2 editor, so you can better understand how it works.

Pavlo Okhrem
Article by Pavlo Okhrem

CEO/Co-founder at eLogic Commerce. E-commerce expert. International conferences speaker.