Documentation Home »The Oro Cookbook »Entities »How to Create a Basic Datagrid
2.3 version

How to Create a Basic Datagrid

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:

Data Source

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

Displayed Columns

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
# src/AppBundle/Resources/config/oro/datagrids.yml
datagrids:
    app-tasks-grid:
        # ...
        columns:
            id:
                label: ID
                frontend_type: integer
            subject:
                label: Subject
            description:
                label: Description
            dueDate:
                label: Due Date
                frontend_type: datetime
            taskPriority:
                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
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
# src/AppBundle/Resources/config/oro/datagrids.yml
datagrids:
    app-tasks-grid:
        # ...
        sorters:
            columns:
                id:
                    data_name: task.id
                subject:
                    data_name: task.subject
                description:
                    data_name: task.description
                dueDate:
                    data_name: task.dueDate
                taskPriority:
                    data_name: priority.label
            default:
                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 data grid’s query builder.

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

The Complete Datagrid Configuration

The final data grid configuration now looks like this:

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

use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Template;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;

/**
 * @Route("/task")
 */
class TaskController extends Controller
{
    /**
     * @Route("/", name="app_task_index")
     * @Template()
     */
    public function indexAction()
    {
        return array();
    }
}

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

1
2
3
4
5
{# src/AppBundle/Resources/views/Task/index.html.twig #}
{% extends 'OroUIBundle:actions:index.html.twig' %}

{% set gridName = 'app-tasks-grid' %}
{% 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.

Browse maintained versions:
current1.102.02.32.4
ssossossosso