An admin grid: UI components

Grids and forms in the Magento admin panel are built not with templates but with UI components. A grid is described in an XML file, and Magento adds sorting, filters, paging and column selection itself. This is one of the bulkiest parts of the platform: the XML gets long, and a typo in a name gives an empty page with no explanation. So only a minimal working version is shown here.

What a grid consists of

Part	Where it is
The grid definition	`view/adminhtml/ui_component/hello_review_listing.xml`
The data source	An entry in `etc/di.xml`
Attaching it to the page	The `view/adminhtml/layout/hello_review_index.xml` layout

app/code/Acme/Hello/
├── etc/
│   └── di.xml                                  changed
└── view/
    └── adminhtml/
        ├── layout/
        │   └── hello_review_index.xml          changed
        └── ui_component/
            └── hello_review_listing.xml        new file

The data source

A grid needs a collection. A separate class is not required — a virtual type in etc/di.xml is enough:

<!-- app/code/Acme/Hello/etc/di.xml -->
<virtualType name="Acme\Hello\Model\ResourceModel\Review\Grid\Collection"
             type="Magento\Framework\View\Element\UiComponent\DataProvider\SearchResult">
    <arguments>
        <argument name="mainTable" xsi:type="string">acme_hello_review</argument>
        <argument name="resourceModel" xsi:type="string">Acme\Hello\Model\ResourceModel\Review</argument>
    </arguments>
</virtualType>
 
<type name="Magento\Framework\View\Element\UiComponent\DataProvider\CollectionFactory">
    <arguments>
        <argument name="collections" xsi:type="array">
            <item name="hello_review_listing_data_source" xsi:type="string">Acme\Hello\Model\ResourceModel\Review\Grid\Collection</item>
        </argument>
    </arguments>
</type>

The first entry creates a collection for the acme_hello_review table, the second registers it under the name hello_review_listing_data_source. This name appears three more times in the next file and must be the same everywhere.

The grid definition

<?xml version="1.0"?>
<!-- app/code/Acme/Hello/view/adminhtml/ui_component/hello_review_listing.xml -->
<listing xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Ui:etc/ui_configuration.xsd">
    <argument name="data" xsi:type="array">
        <item name="js_config" xsi:type="array">
            <item name="provider" xsi:type="string">hello_review_listing.hello_review_listing_data_source</item>
        </item>
    </argument>
    <settings>
        <spinner>hello_review_columns</spinner>
        <deps>
            <dep>hello_review_listing.hello_review_listing_data_source</dep>
        </deps>
    </settings>
 
    <dataSource name="hello_review_listing_data_source" component="Magento_Ui/js/grid/provider">
        <settings>
            <storageConfig>
                <param name="indexField" xsi:type="string">review_id</param>
            </storageConfig>
            <updateUrl path="mui/index/render"/>
        </settings>
        <aclResource>Acme_Hello::reviews</aclResource>
        <dataProvider class="Magento\Framework\View\Element\UiComponent\DataProvider\DataProvider"
                      name="hello_review_listing_data_source">
            <settings>
                <requestFieldName>id</requestFieldName>
                <primaryFieldName>review_id</primaryFieldName>
            </settings>
        </dataProvider>
    </dataSource>
 
    <listingToolbar name="listing_top">
        <columnsControls name="columns_controls"/>
        <filters name="listing_filters"/>
        <paging name="listing_paging"/>
    </listingToolbar>
 
    <columns name="hello_review_columns">
        <column name="review_id" sortOrder="10">
            <settings>
                <filter>textRange</filter>
                <label translate="true">ID</label>
                <sorting>desc</sorting>
            </settings>
        </column>
        <column name="author" sortOrder="20">
            <settings>
                <filter>text</filter>
                <label translate="true">Author</label>
            </settings>
        </column>
        <column name="rating" sortOrder="30">
            <settings>
                <filter>textRange</filter>
                <label translate="true">Rating</label>
            </settings>
        </column>
    </columns>
</listing>

Section	What it is responsible for
`dataSource`	Where rows come from and which permission is required
`listingToolbar`	The bar above the grid: filters, pages, column selection
`columns`	The columns; a column name equals the table field name

Attaching it to the page

In the page layout from the previous lesson replace the template block with the component:

<!-- app/code/Acme/Hello/view/adminhtml/layout/hello_review_index.xml -->
<referenceContainer name="content">
    <uiComponent name="hello_review_listing"/>
</referenceContainer>

The component name is the file name without the extension. Run bin/magento cache:clean and open Catalog → Hello Reviews: a grid appears with the reviews from the patch, sorting by a click on a header, filters and paging.

What a form requires

An edit form is built the same way, but has more parts:

a view/adminhtml/ui_component/hello_review_form.xml file with the fields;
your own data provider class extending Magento\Ui\DataProvider\AbstractDataProvider that hands the record values to the form;
the Edit, Save and Delete actions in Controller/Adminhtml/Review;
an actions column in the grid that leads to the form.

Writing all of this from scratch is hard. The usual approach is to take a small core module as a model, for example CMS blocks in vendor/magento/module-cms, copy its files and replace the names.

Common mistake

The names do not match: the file is called hello_review_listing.xml, but provider, deps or di.xml says hello_reviews_listing_data_source. The page opens, but a loading spinner turns forever instead of the grid. Check every place where the data source name occurs, and look into the browser console and var/log/system.log.

Thanks for reading!