Important

You are browsing the documentation for version 4.1 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Datagrids

Creating a basic datagrid to display the data of all tasks requires three steps:

  1. Configure the datagrid

  2. Create a controller and template

  3. Add a link to the grid to the application menu

Configure the Grid

The datagrid configuration happens in the datagrids.yml file in the configuration directory of your bundle and is divided into several sections:

Datasource

The source option is used to configure a Doctrine query builder that is used to fetch the data to be displayed in the grid:

 1# src/AppBundle/Resources/config/oro/datagrids.yml
 2datagrids:
 3    app-tasks-grid:
 4        source:
 5            type: orm
 6            query:
 7                select:
 8                    - task.id
 9                    - task.subject
10                    - task.description
11                    - task.dueDate
12                    - priority.label AS taskPriority
13                from:
14                    - { table: AppBundle:Task, alias: task }
15                join:
16                    left:
17                        - { join: task.priority, alias: priority }

Displayed Columns

Then, the columns option needs to be used to configure how which data will be displayed:

 1# src/AppBundle/Resources/config/oro/datagrids.yml
 2datagrids:
 3    app-tasks-grid:
 4        # ...
 5        columns:
 6            id:
 7                label: ID
 8                frontend_type: integer
 9            subject:
10                label: Subject
11            description:
12                label: Description
13            dueDate:
14                label: Due Date
15                frontend_type: datetime
16            taskPriority:
17                label: Priority

For each column, the frontend_type option can be used to customize how data will be displayed (by default, the data will be shown as is).

Column Sorters

Use the sorters option to define on which columns’ header the user can click to order by the data:

 1# src/AppBundle/Resources/config/oro/datagrids.yml
 2datagrids:
 3    app-tasks-grid:
 4        # ...
 5        sorters:
 6            columns:
 7                id:
 8                    data_name: task.id
 9                subject:
10                    data_name: task.subject
11                description:
12                    data_name: task.description
13                dueDate:
14                    data_name: task.dueDate
15                taskPriority:
16                    data_name: priority.label
17            default:
18                dueDate: DESC

Each key under sorters.columns refers to one of the displayed columns. The data_name option is the term that will be used as the order by term in the Doctrine query.

Data Filters

Data filters are UI elements that allow the user to filter the data being displayed in the data grid. List all the attributes for which a filter should be shown under the filters.columns key. To configure the filter for a certain property two options are needed:

type configures the UI type of the filter. The type of the filter should be chosen based on the data type of the underlying attribute.

The data_name denotes the name of the property to filter and will be used as is to modify the datagrid’s query builder.

 1# src/AppBundle/Resources/config/oro/datagrids.yml
 2datagrids:
 3    app-tasks-grid:
 4        # ...
 5        filters:
 6            columns:
 7                id:
 8                    type: number
 9                    data_name: task.id
10                subject:
11                    type: string
12                    data_name: task.subject
13                description:
14                    type: string
15                    data_name: task.description
16                dueDate:
17                    type: datetime
18                    data_name: task.dueDate
19                taskPriority:
20                    type: string
21                    data_name: priority.label

Complete Datagrid Configuration

The final datagrid configuration now looks like this:

 1# src/AppBundle/Resources/config/oro/datagrids.yml
 2datagrids:
 3    app-tasks-grid:
 4        source:
 5            type: orm
 6            query:
 7                select:
 8                    - task.id
 9                    - task.subject
10                    - task.description
11                    - task.dueDate
12                    - priority.label AS taskPriority
13                from:
14                    - { table: AppBundle:Task, alias: task }
15                join:
16                    left:
17                        - { join: task.priority, alias: priority }
18        columns:
19            id:
20                label: ID
21                frontend_type: integer
22            subject:
23                label: Subject
24            description:
25                label: Description
26            dueDate:
27                label: Due Date
28                frontend_type: datetime
29            taskPriority:
30                label: Priority
31        sorters:
32            columns:
33                id:
34                    data_name: task.id
35                subject:
36                    data_name: task.subject
37                description:
38                    data_name: task.description
39                dueDate:
40                    data_name: task.dueDate
41                taskPriority:
42                    data_name: priority.label
43            default:
44                dueDate: DESC
45        filters:
46            columns:
47                id:
48                    type: number
49                    data_name: task.id
50                subject:
51                    type: string
52                    data_name: task.subject
53                description:
54                    type: string
55                    data_name: task.description
56                dueDate:
57                    type: datetime
58                    data_name: task.dueDate
59                taskPriority:
60                    type: string
61                    data_name: priority.label

Create the Controller and View

To make your datagrid accessible you need to create a controller that can be visited by the user which will serve a view that renders the configured datagrid:

 1// src/AppBundle/Controller/TaskController.php
 2namespace AppBundle\Controller;
 3
 4use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
 5use Sensio\Bundle\FrameworkExtraBundle\Configuration\Template;
 6use Symfony\Bundle\FrameworkBundle\Controller\Controller;
 7
 8/**
 9 * @Route("/task")
10 */
11class TaskController extends Controller
12{
13    /**
14     * @Route("/", name="app_task_index")
15     * @Template()
16     */
17    public function indexAction()
18    {
19        return [];
20    }
21}

The view can be very simple if you extend the OroUIBundle:actions:index.html.twig template:

1{# src/AppBundle/Resources/views/Task/index.html.twig #}
2{% extends 'OroUIBundle:actions:index.html.twig' %}
3
4{% set gridName = 'app-tasks-grid' %}
5{% set pageTitle = 'Task' %}

You simply need to configure the name of your datagrid and the title you wish to be displayed. Everything else is handled by the base template from the OroUIBundle.

Key Classes

  • Datagrid\Manager - responsible of preparing the grid and its configuration.

  • Datagrid\Builder - responsible for creating and configuring the datagrid object and its datasource. Contains registered datasource type and extensions, also it performs check for datasource availability according to ACL

  • Datagrid\Datagrid - the main grid object, has knowledge ONLY about the datasource object and the interaction with it, all further modifications of the results and metadata come from the extensions ExtensionAcceptor - is a visitable mediator, contains all applied extensions and provokes visits at different points of the interactions.

  • Extension\ExtensionVisitorInterface - visitor interface

  • Extension\AbstractExtension - basic empty implementation

  • Datasource\DatasourceInterface - link object between data and grid. Should provide results as array of ResultRecordInterface compatible objects

  • Provider\SystemAwareResolver - resolves specific grid YAML syntax expressions. For more information, see the references in configuration topic.

Mixin

Mixin is a datagrid that contains additional (common) information for use by other datagrids.

Configuration Syntax

 1 datagrids:
 2
 3     # configuration mixin with column, sorter and filter for an entity identifier
 4     acme-demo-common-identifier-datagrid-mixin:
 5         source:
 6             type: orm
 7             query:
 8                 select:
 9                     # alias that will be replaced by an alias of the root entity
10                     - __root_entity__.id as identifier
11         columns:
12             identifier:
13                 frontend_type: integer
14         sorters:
15             data_name: identifier
16         filters:
17             columns:
18                 identifier:
19                     type: number
20                     data_name: identifier
21
22     acme-demo-user-datagrid:
23         # one or several mixins
24         mixins:
25             - acme-demo-datagrid-mixin
26             - ...
27             - ...
28         source:
29             type: orm
30             query:
31                 from:
32                     { table: AcmeDemoBundle:User, alias:u }

Related Articles