UI component listing do Magento 2: grid do admin abre vazia

A grid do meu módulo abria bonitinha: cabeçalho das colunas montado, rodapé dizendo 0 registros e nada no meio. O erro de verdade estava escondido na aba Network do navegador — a chamada para mui/index/render voltava com Not registered handle roger_item_listing_data_source. Falta ligar o dataSource do listing.xml a uma collection, e esse vínculo mora no di.xml.

Registre a collection no di.xml

A classe MagentoFrameworkViewElementUiComponentDataProviderDataProvider não sabe ler tabela nenhuma sozinha. Ela pergunta ao CollectionFactory qual collection responde pelo nome do dataSource. Se o nome não estiver no array collections, sai a exceção acima e a grid fica vazia.

<virtualType name="RogerCatalogoModelResourceModelItemGridCollection"
    type="MagentoFrameworkViewElementUiComponentDataProviderSearchResult">
    <arguments>
        <argument name="mainTable" xsi:type="string">roger_catalogo_item</argument>
        <argument name="resourceModel" xsi:type="string">RogerCatalogoModelResourceModelItem</argument>
        <argument name="identifierName" xsi:type="string">entity_id</argument>
    </arguments>
</virtualType>

<type name="MagentoFrameworkViewElementUiComponentDataProviderCollectionFactory">
    <arguments>
        <argument name="collections" xsi:type="array">
            <item name="roger_item_listing_data_source" xsi:type="string">RogerCatalogoModelResourceModelItemGridCollection</item>
        </argument>
    </arguments>
</type>

Repare que não criei classe nenhuma: o virtualType em cima do SearchResult já entrega paginação, ordenação e filtro da grid prontos. O identifierName não é enfeite: sem ele o SearchResult assume que a chave primária se chama id, e aí o filtro por ID e a edição inline param de casar. Classe própria só quando você precisa de join ou de filtro fixo, e mesmo aí o pai continua sendo o SearchResult.

Um nome só, em três lugares

Essa é a pegadinha que me custou uma tarde. O name do item acima tem que ser idêntico, caractere por caractere, ao name do dataSource e ao name do dataProvider dentro dele, em view/adminhtml/ui_component/roger_item_listing.xml.

<dataSource name="roger_item_listing_data_source" component="Magento_Ui/js/grid/provider">
    <dataProvider name="roger_item_listing_data_source"
        class="MagentoFrameworkViewElementUiComponentDataProviderDataProvider">
        <settings>
            <requestFieldName>entity_id</requestFieldName>
            <primaryFieldName>entity_id</primaryFieldName>
        </settings>
    </dataProvider>
</dataSource>

Depois de mexer no di.xml, limpe o cache de configuração. Em developer mode isso basta; em produção, recompile o DI antes de testar:

bin/magento cache:clean config

# só em modo produção
bin/magento setup:di:compile

Se a exceção sumir e a grid continuar sem linhas, o problema mudou de endereço: aí é mainTable errada ou filtro sobrando no resource model. Ligue o bin/magento dev:query-log:enable, recarregue a grid e leia o SELECT que saiu de verdade.