Reference - Grid arguments

A Loki_AdminComponents grid is a block that is defined within the XML layout by referring to the PHTML template Loki_AdminComponents::grid.phtml and accompanied with various required or optional arguments.

<block name="yireo-training.example-admin.grid" template="Loki_AdminComponents::grid.phtml">
    <arguments>
        <argument name="foo" xsi:type="string">bar</argument>
    </arguments>
</block>

XML layout base arguments

A grid block can be supplied with the following XML arguments:

provider (string or object, required)

A class or classname supported by available provider handlers, like collections, repositories or array providers.

<block name="yireo-training.example-admin.grid">
    <arguments>
        <argument name="provider" xsi:type="string">Magento\Eav\Model\ResourceModel\Entity\Type\Collection</argument>
    </arguments>
</block>

If you want to pass the class as an object, it needs to implement Magento\Framework\View\Element\Block\ArgumentInterface.

provider_handler (string)

A string pointing to the provider handler. Often this is not needed, because the provider handler is detected automatically. But it can be used if the automatic detection fails or if you have added your own custom provider handler.

<block name="yireo-training.example-admin.grid">
    <arguments>
        <argument name="provider_handler" xsi:type="string">repository</argument>
    </arguments>
</block>

namespace (string)

A namespace that could correspond with the UI Bookmark name of a core grid. If you don't need UI Bookmark behaviour, you could skip this.

<block name="yireo-training.example-admin.grid">
    <arguments>
        <argument name="namespace" xsi:type="string">example</argument>
    </arguments>
</block>

resource_model (string or object)

Sometimes, a repository handler is unable to retrieve column-information from the repository. By providing the classname for the resource_model, you can help the repository handler determine things automatically. This, or you need to supply the columns in a different way. Only use this if you have determined that it does not work without.

<block name="yireo-training.example-admin.grid">
    <arguments>
        <argument name="provider" xsi:type="string">Magento\Cms\Model\PageRepository</argument>
        <argument name="resource_model" xsi:type="string">Magento\Cms\Model\ResourceModel\Page</argument>
    </arguments>
</block>

If you want to pass the class as an object, it needs to implement Magento\Framework\View\Element\Block\ArgumentInterface.

columns (array)

By default, the grid tries to display all available columns, but this might lead to results that are slightly off. By adding the columns property, you can override columns where needed.

<block name="yireo-training.example-admin.grid">
    <arguments>
        <argument name="columns" xsi:type="array">
            <item name="id" xsi:type="array">
                <item name="label" xsi:type="string">Item ID</item>
            </item>
            <item name="name" xsi:type="string">
                <item name="label" xsi:type="string">Item Name</item>
            </item>
        </argument>
    </arguments>
</block>

edit_url (string)

If the URL to edit an item is not */*/form, then it needs to be changed with this argument.

<block name="yireo-training.example-admin.grid">
    <arguments>
        <argument name="edit_url" xsi:type="string">*/*/edit</argument>
    </arguments>
</block>

hide_actions (boolean)

A grid by default shows various actions to interact with the grid: Buttons to create new items, edit-action. With this flag, you can hide actions. A good example for this would be an array provider grid (with which you can't edit data anyway) or a grid for which you don't have a form yet.

<block name="yireo-training.example-admin.grid">
    <arguments>
        <argument name="hide_actions" xsi:type="boolean">true</argument>
    </arguments>
</block>

searchable_fields (array)

A simple array of fields that are allowed to search through. By default, this is all fields.

<block name="yireo-training.example-admin.grid">
    <arguments>
        <argument name="searchable_fields" xsi:type="array">
            <item name="name" xsi:type="string">Name</item>
            <item name="description" xsi:type="string">Description</item>
        </argument>
    </arguments>
</block>

XML layout column arguments

label (string)

By default, the column label is extracted by converting the field name (example_item_name) into readable text (pascal-case with dashes replaced with spaces). The label can be customized with this argument.

<block name="yireo-training.example-admin.grid">
    <arguments>
        <argument name="columns" xsi:type="array">
            <item name="name" xsi:type="string">
                <item name="label" xsi:type="string">Item Name</item>
            </item>
        </argument>
    </arguments>
</block>

position (number)

Each column is ordered in the order that they are detected, except for when the grid has been saved before in the UI bookmark logic. You can change this with this argument.

<block name="yireo-training.example-admin.grid">
    <arguments>
        <argument name="columns" xsi:type="array">
            <item name="name" xsi:type="string">
                <item name="position" xsi:type="number">3</item>
            </item>
        </argument>
    </arguments>
</block>

cell_template (string)

A column value is rendered via a cell template. By default, this is just a simple text output. By overriding the PHTML template you can customize things at will;

<block name="yireo-training.example-admin.grid">
    <arguments>
        <argument name="columns" xsi:type="array">
            <item name="description" xsi:type="string">
                <item name="cell_template" xsi:type="string">Yireo_Example::grid/cell/description.phtml</item>
            </item>
        </argument>
    </arguments>
</block>

Note that in the module Loki_AdminComponents various example templates can be found.

visible (boolean)

Each column that is detected is visible by default, unless the UI bookmark mechanism says otherwise. With the flag visible you can override this.

<block name="yireo-training.example-admin.grid">
    <arguments>
        <argument name="columns" xsi:type="array">
            <item name="created_at" xsi:type="string">
                <item name="visible" xsi:type="boolean">false</item>
            </item>
        </argument>
    </arguments>
</block>