How to Create Admin Grid in Magento 2
In this article, we will find how to create an Admin Grid in Magento 2 backend. As you know, Magento 2 Grid is a kind of table which listing the items in your database table and provide you some features like: sort, filter, delete, update item, etc. The example for this is the grid of products, grid of customer.
Magento 2 provide two ways to create Admin Grid: using layout and using component. We will find out the detail for both of them. Before we continue please follow this articles to create a simple module with admin menu, router which we will use to learn about grid. In this article, I will use the sample module Mageplaza_Example with some demo data:
To Create Admin Grid
- Step 1: Create database schema
- Step 2: Create admin menu
- Step 3: Create Controller
- Step 4: Declare resource
- Step 5: Create Admin Grid using Component
- Step 6: Create Admin Grid using Layout
Step 1: Create database schema
Database: We will use a simple database
Create Resource Model and Model Collection — Model/Resource Model/Collection — like this
Step 2: Create admin menu
Admin menu/Route: we will use the route example for our admin page and the menu link to:
example/blog/indexStep 3: Create Controller
Create controller file: please read the Create Controller article for the detail.
Create controller file called index.php
app/code/Mageplaza/Example/Controller/Adminhtml/Blog/Index.phpWith the following content:
<?php
namespace Mageplaza\Example\Controller\Adminhtml\Blog;class Index extends \Magento\Backend\App\Action
{
protected $resultPageFactory = false;
public function __construct(
\Magento\Backend\App\Action\Context $context,
\Magento\Framework\View\Result\PageFactory $resultPageFactory
) {
parent::__construct($context);
$this->resultPageFactory = $resultPageFactory;
} public function execute()
{
//Call page factory to render layout and page content
$resultPage = $this->resultPageFactory->create(); //Set the menu which will be active for this page
$resultPage->setActiveMenu('Mageplaza_Example::blog_manage');
//Set the header title of grid
$resultPage->getConfig()->getTitle()->prepend(__('Manage Blogs')); //Add bread crumb
$resultPage->addBreadcrumb(__('Mageplaza'), __('Mageplaza'));
$resultPage->addBreadcrumb(__('Hello World'), __('Manage Blogs')); return $resultPage;
} /*
* Check permission via ACL resource
*/
protected function _isAllowed()
{
return $this->_authorization->isAllowed('Mageplaza_Example::blog_manage');
}
}
Step 4: Declare resource
Declare resource in dependency injection file Now we will create di.xml file which will connect to the Model to get the data for our grid.
File: app/code/Mageplaza/Example/etc/di.xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
<virtualType name="Mageplaza\Example\Model\ResourceModel\Blog\Collection" type="Magento\Framework\View\Element\UiComponent\DataProvider\SearchResult">
<arguments>
<argument name="mainTable" xsi:type="string">mageplaza_blog</argument>
<argument name="resourceModel" xsi:type="string">Mageplaza\Example\Model\ResourceModel\Blog</argument>
</arguments>
</virtualType>
<type name="Magento\Framework\View\Element\UiComponent\DataProvider\CollectionFactory">
<arguments>
<argument name="collections" xsi:type="array">
<item name="example_blog_grid_data_source" xsi:type="string">Mageplaza\Example\Model\ResourceModel\Blog\Collection</item>
</argument>
</arguments>
</type>
</config>This file will declare the blog collection class, table and resourceModel for the table. This source will be called in the layout file to get data for grid.
There are 2 ways to create admin grid, in this post’s scope, we will talk about both of them.
Step 5: Create Admin Grid using Component
Step 5.1: Create layout file
For the action example/blog/index, we will create a layout file named example_blog_index.xml
File: app/code/Mageplaza/Example/view/adminhtml/layout/example_blog_index.xml
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
<update handle="styles"/>
<body>
<referenceContainer name="content">
<uiComponent name="mageplaza_blog_grid"/>
</referenceContainer>
</body>
</page>In this layout file, we declare an uiComponent for the content of this page.
Step 5.2: Create component layout file
As declaration in layout file, we will create a component file mageplaza_blog_grid.xml
File: app/code/Mageplaza/Example/view/adminhtml/ui_component/mageplaza_blog_grid.xml
<?xml version="1.0" encoding="UTF-8"?>
<listing xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Ui:etc/ui_configuration.xsd">
<!--Declare data source, columns list, button...-->
<argument name="data" xsi:type="array">
<item name="js_config" xsi:type="array">
<item name="provider" xsi:type="string">mageplaza_blog_grid.example_blog_grid_data_source</item>
<item name="deps" xsi:type="string">mageplaza_blog_grid.example_blog_grid_data_source</item>
<!--Declare the data source name which will be defined below-->
</item>
<item name="spinner" xsi:type="string">example_blog_columns</item>
<!--Declare the listing of columns which will be defined below-->
<item name="buttons" xsi:type="array">
<item name="add" xsi:type="array">
<item name="name" xsi:type="string">add</item>
<item name="label" xsi:type="string" translate="true">Add New Blog</item>
<item name="class" xsi:type="string">primary</item>
<item name="url" xsi:type="string">*/*/new</item>
</item>
<!--The button on the top of the Grid-->
</item>
</argument>
<dataSource name="example_blog_grid_data_source">
<!--The data source-->
<argument name="dataProvider" xsi:type="configurableObject">
<argument name="class" xsi:type="string">Magento\Framework\View\Element\UiComponent\DataProvider\DataProvider</argument>
<argument name="name" xsi:type="string">example_blog_grid_data_source</argument>
<argument name="primaryFieldName" xsi:type="string">blog_id</argument>
<argument name="requestFieldName" xsi:type="string">id</argument>
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="component" xsi:type="string">Magento_Ui/js/grid/provider</item>
<item name="update_url" xsi:type="url" path="mui/index/render"/>
<item name="storageConfig" xsi:type="array">
<item name="indexField" xsi:type="string">blog_id</item>
</item>
</item>
</argument>
</argument>
</dataSource>
<columns name="example_blog_columns">
<!--The list of columns-->
<selectionsColumn name="ids">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="indexField" xsi:type="string">blog_id</item>
</item>
</argument>
</selectionsColumn>
<column name="blog_id">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="filter" xsi:type="string">text</item>
<item name="sorting" xsi:type="string">asc</item>
<item name="label" xsi:type="string" translate="true">ID</item>
</item>
</argument>
</column>
<column name="title">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="filter" xsi:type="string">text</item>
<item name="sorting" xsi:type="string">asc</item>
<item name="label" xsi:type="string" translate="true">Title</item>
</item>
</argument>
</column>
<column name="creation_time" class="Magento\Ui\Component\Listing\Columns\Date">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="filter" xsi:type="string">dateRange</item>
<item name="component" xsi:type="string">Magento_Ui/js/grid/columns/date</item>
<item name="dataType" xsi:type="string">date</item>
<item name="label" xsi:type="string" translate="true">Created Date</item>
</item>
</argument>
</column>
</columns>
</listing>With this code, you will know how to declare Grid layout (button, columns), call data source. Please refresh the cache, and access to this grid page, the admin grid will show up like this:
Step 5.3: Create a container
As I said on the top of this page, the Magento 2 Grid will support some actions to interact with grid like: sort, filter, action delete/update etc. The sort feature is a default action for the grid. You can click on the column header to sorting the items. We will find out how to built the other features for our grid.
Prepare for this, we will create a container element under the parent listing in the component layout file:
File: app/code/Mageplaza/Example/view/adminhtml/ui_component/mageplaza_blog_grid.xml
<?xml version="1.0" encoding="UTF-8"?>
<listing xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Ui:etc/ui_configuration.xsd">
<!-- ... other block of code --> <container name="listing_top">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="template" xsi:type="string">ui/grid/toolbar</item>
</item>
</argument>
</container>
</listing>
Step 5.4: Create a Bookmark
This argument is used to define the template Magento/Ui/view/base/web/templates/grid/toolbar.html which will be loaded to define the knockout js for handling all ajax update action in this grid. We will define above features inside of this container. You can place this container element before or after the columns element to define the position of the toolbar (above or below the columns). Let’s see the detail for each action: Bookmark
<bookmark name="bookmarks">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="storageConfig" xsi:type="array">
<item name="namespace" xsi:type="string">mageplaza_blog_grid</item>
</item>
</item>
</argument>
</bookmark>This will add the bookmark feature which allows admin setup difference state of the grid. Each state may have a difference columns list. So with each admin user, they can choose to show the information which are relevant to him.
Step 5.5: Column controls
This node will add a columns list box which allow the admin user can choose which columns can be shown up on grid. After changing this list, admin can save that state as a bookmark which allow to access this state quickly.
<component name="columns_controls">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="columnsData" xsi:type="array">
<item name="provider" xsi:type="string">mageplaza_blog_grid.mageplaza_blog_grid.example_blog_columns</item>
</item>
<item name="component" xsi:type="string">Magento_Ui/js/grid/controls/columns</item>
<item name="displayArea" xsi:type="string">dataGridActions</item>
</item>
</argument>
</component>Step 5.6: Full text search
This node will add a search box at the top of Grid. You can use this to search all the data in the table.
<filterSearch name="fulltext">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="provider" xsi:type="string">mageplaza_blog_grid.example_blog_grid_data_source</item>
<item name="chipsProvider" xsi:type="string">mageplaza_blog_grid.mageplaza_blog_grid.listing_top.listing_filters_chips</item>
<item name="storageConfig" xsi:type="array">
<item name="provider" xsi:type="string">mageplaza_blog_grid.mageplaza_blog_grid.listing_top.bookmarks</item>
<item name="namespace" xsi:type="string">current.search</item>
</item>
</item>
</argument>
</filterSearch>Step 5.7: Filter
This node define the filter box for each column. You can see this by click to the Filter button at the top of the grid.
<filters name="listing_filters">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="columnsProvider" xsi:type="string">mageplaza_blog_grid.mageplaza_blog_grid.example_blog_columns</item>
<item name="storageConfig" xsi:type="array">
<item name="provider" xsi:type="string">mageplaza_blog_grid.mageplaza_blog_grid.listing_top.bookmarks</item>
<item name="namespace" xsi:type="string">current.filters</item>
</item>
<item name="childDefaults" xsi:type="array">
<item name="provider" xsi:type="string">mageplaza_blog_grid.mageplaza_blog_grid.listing_top.listing_filters</item>
<item name="imports" xsi:type="array">
<item name="visible" xsi:type="string">mageplaza_blog_grid.mageplaza_blog_grid.example_blog_columns.${ $.index }:visible</item>
</item>
</item>
</item>
</argument>
</filters>Step 5.8: Mass actions
This node will add the mass action select to the grid. The Admin can use this action to take some action quickly on multiple items.
<massaction name="listing_massaction">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="selectProvider" xsi:type="string">mageplaza_blog_grid.mageplaza_blog_grid.example_blog_columns.ids</item>
<item name="component" xsi:type="string">Magento_Ui/js/grid/tree-massactions</item>
<item name="indexField" xsi:type="string">entity_id</item>
</item>
</argument>
<action name="delete">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="type" xsi:type="string">delete</item>
<item name="label" xsi:type="string" translate="true">Delete</item>
<item name="url" xsi:type="url" path="*/*/massDelete"/>
<item name="confirm" xsi:type="array">
<item name="title" xsi:type="string" translate="true">Delete items</item>
<item name="message" xsi:type="string" translate="true">Are you sure to delete selected blogs?</item>
</item>
</item>
</argument>
</action>
</massaction>Step 5.9: Paging
This node will add the pagination for the grid. This is useful if you have a large of data in the table.
<paging name="listing_paging">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="storageConfig" xsi:type="array">
<item name="provider" xsi:type="string">mageplaza_blog_grid.mageplaza_blog_grid.listing_top.bookmarks</item>
<item name="namespace" xsi:type="string">current.paging</item>
</item>
<item name="selectProvider" xsi:type="string">mageplaza_blog_grid.mageplaza_blog_grid.example_blog_columns.ids</item>
</item>
</argument>
</paging>Step 5.10: Export
This node will add an export button which you can export the data of the grid.
<exportButton name="export_button">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="selectProvider" xsi:type="string">mageplaza_blog_grid.mageplaza_blog_grid.example_blog_columns.ids</item>
</item>
</argument>
</exportButton>Try to clean the cache and go to the grid page, you will see a grid like this:
Step 6: Create Admin Grid using Layout
Important! Skip this step if you have ready done Step 5
You have just find how to add a Magento 2 Grid by using Component. Now we will see how to do it by using normal layout/block file.
Step 6.1: Create block for this grid
File: app/code/Mageplaza/Example/Block/Adminhtml/Blog/Grid.php
<?php
namespace Mageplaza\Example\Block\Adminhtml\Blog;
class Grid extends \Magento\Backend\Block\Widget\Grid\Container
{
protected function _construct()
{
$this->_blockGroup = 'Mageplaza_Example';
$this->_controller = 'adminhtml_blog';
$this->_headerText = __('Manage Blogs');
$this->_addButtonLabel = __('Add New Blog');
parent::_construct();
}
}The Grid block will extend \Magento\Backend\Block\Widget\Grid\Container and define some variable in the _construct() method. — _blockGroup is the name of our module with format VendorName_ModuleName — _controller is the path to the Grid block inside the Block folder. In this example, I put the Grid.php file inside of the Adminhtml/Blog folder — _headerText is the Grid page title — _addButtonLabel is the label of the Add new button.
Step 6.2: Create layout file
Now we will need a layout file to connect with Grid Block and render the grid. Let’s create this file:
File: app/code/Mageplaza/Example/view/adminhtml/layout/example_blog_index.xml
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
<update handle="styles"/>
<body>
<referenceContainer name="content">
<!--<uiComponent name="mageplaza_blog_grid"/>-->
<block class="Mageplaza\Example\Block\Adminhtml\Blog\Grid" name="mageplaza_blog_grid">
<block class="Magento\Backend\Block\Widget\Grid" name="mageplaza_blog_grid.grid" as="grid">
<arguments>
<argument name="id" xsi:type="string">blog_id</argument>
<argument name="dataSource" xsi:type="object">Mageplaza\Example\Model\ResourceModel\Blog\Collection</argument>
<argument name="default_sort" xsi:type="string">id</argument>
<argument name="default_dir" xsi:type="string">ASC</argument>
<argument name="save_parameters_in_session" xsi:type="string">1</argument>
</arguments>
<block class="Magento\Backend\Block\Widget\Grid\ColumnSet" name="mageplaza_blog_grid.grid.columnSet" as="grid.columnSet">
<arguments>
<argument name="rowUrl" xsi:type="array">
<item name="path" xsi:type="string">*/*/edit</item>
</argument>
</arguments>
<block class="Magento\Backend\Block\Widget\Grid\Column" as="id">
<arguments>
<argument name="header" xsi:type="string" translate="true">ID</argument>
<argument name="index" xsi:type="string">blog_id</argument>
<argument name="type" xsi:type="string">text</argument>
<argument name="column_css_class" xsi:type="string">col-id</argument>
<argument name="header_css_class" xsi:type="string">col-id</argument>
</arguments>
</block>
<block class="Magento\Backend\Block\Widget\Grid\Column" as="title">
<arguments>
<argument name="header" xsi:type="string" translate="true">Title</argument>
<argument name="index" xsi:type="string">title</argument>
<argument name="type" xsi:type="string">text</argument>
<argument name="column_css_class" xsi:type="string">col-id</argument>
<argument name="header_css_class" xsi:type="string">col-id</argument>
</arguments>
</block>
<block class="Magento\Backend\Block\Widget\Grid\Column" as="creation_time">
<arguments>
<argument name="header" xsi:type="string" translate="true">Created Time</argument>
<argument name="index" xsi:type="string">creation_time</argument>
<argument name="type" xsi:type="string">date</argument>
<argument name="column_css_class" xsi:type="string">col-id</argument>
<argument name="header_css_class" xsi:type="string">col-id</argument>
</arguments>
</block>
</block>
</block>
</block>
</referenceContainer>
</body>
</page>In this layout file, we will define some argument for the grid. The main argument is the dataSource. This argument will link with the dataSource which we declare in the di.xml file above to connect to the database and get data for this grid.
Step 6.4: Add Column
The Column set will define the columns which will be display in the grid. If you want to use massAction, you can add this block to the grid element:
<block class="Magento\Backend\Block\Widget\Grid\Massaction" name="mageplaza.example.massaction" as="grid.massaction">
<arguments>
<argument name="massaction_id_field" xsi:type="string">blog_id</argument>
<argument name="form_field_name" xsi:type="string">ids</argument>
<argument name="use_select_all" xsi:type="string">1</argument>
<argument name="options" xsi:type="array">
<item name="disable" xsi:type="array">
<item name="label" xsi:type="string" translate="true">Delete</item>
<item name="url" xsi:type="string">*/*/massDelete</item>
</item>
</argument>
</arguments>
</block>After this, please refresh the cache and go to grid page to see the result. It may display like this:
