Important

You are browsing documentation for version 6.0 of OroCommerce, supported until 2028. Read the documentation for the latest LTS version 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 involves three steps:

Configure the datagrid
Create a controller and template
Add a link to the grid to the application menu

Configure the Grid

Configure the backend datagrid in the /config/oro/datagrids.yml file and the frontend datagrid in the /views/layouts/<theme>/config/datagrids.yml file within the configuration directory of your bundle. The configuration is divided into the sections below.

Datasource

The source option configures a Doctrine query builder that fetches the data displayed in the grid:

src/Acme/Bundle/DemoBundle/Resources/config/oro/datagrids.yml

datagrids:
    acme-demo-question-grid-base:
        source:
            type: orm
            query:
                select:
                    - e.id
                    - e.subject
                    - e.description
                    - e.dueDate
                    - 'priority.label as priorityTitle'
                from:
                    -
                        table: Acme\Bundle\DemoBundle\Entity\Question
                        alias: e
                join:
                    left:
                        - { join: e.priority, alias: priority }

Displayed Columns

Next, use the columns option to configure which data is displayed and how:

src/Acme/Bundle/DemoBundle/Resources/config/oro/datagrids.yml

datagrids:
    acme-demo-question-grid-base:
        columns:
            subject:
                label: acme.demo.question.subject.label
            description:
                label: acme.demo.question.description.label
            dueDate:
                label: acme.demo.question.due_date.label
                frontend_type: datetime
            priorityTitle:
                label: acme.demo.question.priority.label

Keep in mind that the frontend datagrid is configured in the Resources/views/layouts/<theme>/config/datagrids.yml file within the configuration directory of your bundle.

Column Sorters

Use the sorters option to define which column headers the user can click to order the data:

src/Acme/Bundle/DemoBundle/Resources/config/oro/datagrids.yml

datagrids:
    acme-demo-question-grid-base:
        sorters:
            columns:
                subject:
                    data_name: e.subject
                description:
                    data_name: e.description
                dueDate:
                    data_name: e.dueDate
                priorityTitle:
                    data_name: priorityTitle
            default:
                dueDate: DESC

Each key under sorters.columns refers to one displayed column. The data_name option provides the order by term for the Doctrine query.

Data Filters

Data filters are UI elements that let the user filter the data displayed in the data grid. List every attribute that needs a filter under the filters.columns key. Configuring a filter for a property requires two options:

The type configures the UI type of the filter. Choose it 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.

src/Acme/Bundle/DemoBundle/Resources/config/oro/datagrids.yml

datagrids:
    acme-demo-question-grid-base:
        filters:
            columns:
                subject:
                    data_name: e.subject
                    type: string
                description:
                    data_name: e.description
                    type: string
                dueDate:
                    data_name: e.dueDate
                    type: datetime
                priorityTitle:
                    type: entity
                    data_name: priority.id
                    options:
                        field_type: Symfony\Bridge\Doctrine\Form\Type\EntityType
                        field_options: { class: Acme\Bundle\DemoBundle\Entity\Priority, choice_label: label }

Complete Datagrid Configuration

The final datagrid configuration now looks like this:

src/Acme/Bundle/DemoBundle/Resources/config/oro/datagrids.yml

datagrids:
    acme-demo-question-grid-base:
        extended_entity_name: Acme\Bundle\DemoBundle\Entity\Question
        source:
            type: orm
            query:
                select:
                    - e.id
                    - e.subject
                    - e.description
                    - e.dueDate
                    - 'priority.label as priorityTitle'
                from:
                    -
                        table: Acme\Bundle\DemoBundle\Entity\Question
                        alias: e
                join:
                    left:
                        - { join: e.priority, alias: priority }
        columns:
            subject:
                label: acme.demo.question.subject.label
            description:
                label: acme.demo.question.description.label
            dueDate:
                label: acme.demo.question.due_date.label
                frontend_type: datetime
            priorityTitle:
                label: acme.demo.question.priority.label
        sorters:
            columns:
                subject:
                    data_name: e.subject
                description:
                    data_name: e.description
                dueDate:
                    data_name: e.dueDate
                priorityTitle:
                    data_name: priorityTitle
            default:
                dueDate: DESC
        filters:
            columns:
                subject:
                    data_name: e.subject
                    type: string
                description:
                    data_name: e.description
                    type: string
                dueDate:
                    data_name: e.dueDate
                    type: datetime
                priorityTitle:
                    type: entity
                    data_name: priority.id
                    options:
                        field_type: Symfony\Bridge\Doctrine\Form\Type\EntityType
                        field_options: { class: Acme\Bundle\DemoBundle\Entity\Priority, choice_label: label }

Create the Controller and View

To make your datagrid accessible, create a controller the user can visit. It serves as a view that renders the configured datagrid:

src/Acme/Bundle/DemoBundle/Controller/QuestionController.php

namespace Acme\Bundle\DemoBundle\Controller;

use Acme\Bundle\DemoBundle\Entity\Question;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Template;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Routing\Annotation\Route;

#[Route(path: '/question', name: 'acme_demo_question_')]
class QuestionController extends AbstractController
{
    #[Route(path: '/', name: 'index')]
    #[Template]
    public function indexAction(): array
    {
        return [
            'entity_class' => Question::class
        ];
    }
}

The view can be straightforward if you extend the @OroUI/actions/index.html.twig template:

src/Acme/Bundle/DemoBundle/Resources/views/Question/index.html.twig

{% extends '@OroUI/actions/index.html.twig' %}
{% import '@OroUI/macros.html.twig' as UI %}
{% set gridName = 'acme-demo-question-grid' %}
{% set pageTitle = 'acme.demo.question.entity_plural_label'|trans %}

Configure the name of your datagrid and the title you want to display. The base template from the OroUIBundle handles everything else.

Link to the Action

Finally, make the action accessible by creating a menu item:

src/Acme/Bundle/DemoBundle/Resources/config/oro/navigation.yml

navigation:
    menu_config:
        items:
            acme_demo_question_list:
                label: acme.demo.question.entity_plural_label
                route: acme_demo_question_index
        tree:
            application_menu:
                children:
                    acme_tab:
                        children:
                            acme_demo_tab:
                                children:
                                    acme_demo_question_list: ~

Note

application_menu is the name of the menu you want to hook your item into. In this case, application_menu is an existing menu that is part of OroPlatform.

Key Classes

Datagrid\Manager — responsible for preparing the grid and its configuration.
Datagrid\Builder — responsible for creating and configuring the datagrid object and its datasource. It contains registered datasource types and extensions, and it also performs a check for datasource availability according to ACL.
Datagrid\Datagrid — the main grid object, has only knowledge about the datasource object and its interaction; all further modifications of the results and metadata come from the extensions. Extension\Acceptor - 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 an 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

src/Acme/Bundle/DemoBundle/Resources/config/oro/datagrids.yml

datagrids:
    # configuration mixin with column, sorter and filter for an entity identifier
    acme-demo-common-user-ownership-datagrid-mixin:
        source:
            query:
                select:
                    - CONCAT(ownerUser.firstName, ' ', ownerUser.lastName) as uOwnerName
                join:
                    left:
                        # _root_entity__ alias that will be replaced by an alias of the root entity
                        - { join: __root_entity__.owner, alias: ownerUser }
        columns:
            uOwnerName:
                label: oro.user.entity_label
        sorters:
            columns:
                uOwnerName:
                    data_name: uOwnerName
        filters:
            columns:
                uOwnerName:
                    data_name: uOwnerName
                    type: string
    acme-demo-question-grid-base:
        # one or several mixins
        mixins:
            - acme-demo-common-user-ownership-datagrid-mixin
        source:
            type: orm
            query:
                from:
                    -
                        table: Acme\Bundle\DemoBundle\Entity\Question
                        alias: e

Related Articles