You are browsing the upcoming documentation for version 5.1 of OroCommerce, OroCRM and OroPlatform, which is scheduled to be released on March 2023. Read version 5.0 (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.

Backend Datagrid

Datagrid is a table-oriented representation of the data from a datasource. It is configured in a YAML file placed in your bundle’s Resources/config/oro folder and called datagrids.yml. This file should contain the root node datagrids and each grid configuration must be placed under it.

Getting Started

Configuration File

To define your own datagrid, create a configuration file as described above. Next, choose the identifier of your future grid and declare it by adding an associative array with the identifier as the key.

For example:

    acme-demo-datagrid:     # grid identifier
        ...                 # configuration will be here


The next step is configuring datasource, a similar array under the source node. Choose datasource type and properly configure it. For further details, check the datasources section.

For example:

            type: orm  # datasource type
                ....   # some query configuration

Datasource as Service

Other than the query yaml-oriented provider, ORM datasource supports an alternative query_builder service-oriented provider. You use any arbitrary method that returns a valid Doctrine\ORM\QueryBuilder instance.

// @acme_demo.user.repository
public class UserRepository
    // ....

    * @return QueryBuilder
    public function getUsersQb()
        return $this->em->createQueryBuilder()
            ->from(User::class, 'u')
            // ->where(...)
            // ->join(...)
            // ->orderBy(...)

In the datagrid configuration, provide the service and method name:

            type: orm  # datasource type
            query_builder: "@acme_demo.user.repository->getUsersQb"

Parameters Binding

If datasource supports parameters binding, you can specify an additional option bind_parameters. For example

            type: orm
                    - u
                    { table: Acme\Bundle\DemoBundle\Entity\User, alias:u }
                    - = :group_id
                group_id: groupId

Parameters binding is also supported while using the query_builder notation for the ORM data source. Each binding calls ->setParameter('group_id', group_id) automatically on the provided builder.

See more in the parameters binding section.

Columns and Properties

The next step is column definition. It is an array as well as other parts of the grid configuration. The root node for columns is columns, the definition key should be a unique column identifier, and the value is an array of the column configuration. The same for properties, but the root node is properties.

A property is something similar to a column but without frontend representation. Properties can be used to pass additional data generated for each row, for example, URLs of row actions.


The column identifier is used for a suggestion, so the best practice is to use an identifier similar to the data identifier (e.g., a field name in DQL).


A row identifier property is usually added for correct work, but for simple grids, it is excessive.

The configuration format is different depending on the column type, but there is a list of keys shared between all types.

  • type - backend formatter type (field by default)
  • label - column title (translated on backend, translation should be placed in the “messages” domain)
  • frontend_type - frontend formatters that process the column value (string by default)
  • editable - is a column editable on the frontend (false by default)
  • data_name - data identifier (column name suggested by default)
  • renderable - whether the column should be rendered (true by default)
  • order - the number of column’s position, allows to change the order of the columns over Datagrid Settings and save it in Grid View (by default it is not defined and the columns are rendered in the order in which they are declared in the configuration)
  • required - if it is true, the column cannot be hidden over Datagrid Settings (false by default)
  • manageable - if it is false, the column does not appear in Datagrid Settings (true by default)
  • disabled - allows removing a column from the grid (false by default)
  • shortenableLabel - could column label be abbreviated or shortened with an ellipsis (true - by default)

For a detailed explanation, see the section on formatters.

Let’s define a few columns:

            type: orm
                select: [ o.firstName, o.lastName, o.age ]
                    - { table: Acme\Bundle\DemoBundle\Entity\SomeEntity, alias: o } #defining table class using FQCN
#                    - { table: '%acme_demo.entity.some_entity.class%', alias: o } #defining table class using parameter
            firstName:                                   # data identifier will be taken from column name
                label: acme.demo.grid.columns.firstName  # translation string
                label: acme.demo.grid.columns.firstName  # translation string
                label: acme.demo.grid.columns.age        # translation string
                frontend_type: number                    # needed for correct l10n (e.g. thousand, decimal separators etc)


After that, you may want to make your columns sortable. The sorting configuration should be placed under the sorters node. The configuration takes the columns and default keys in basic sorter implementation. It is an array of column names where the value is a sorter configuration. One required value, data_name, is responsible for knowing which datagrid should do the sorting.

Let’s make all columns sortable:

        ...                                 # definition from previous examples
                    data_name: o.firstName
                    data_name: o.lastName
                    data_name: o.age
                lastName: DESC              # Default sorting, allowed values ASC|DESC

For detailed explanation, see the section on sorters.

Final Step

The final step is to add a grid to the template. There is a predefined macro for grid rendering defined in @OroDataGrid/macros.html.twig and can be imported by the following call {% import '@OroDataGrid/macros.html.twig' as dataGrid %} . Macro’s name is renderGrid, and it takes two arguments: grid name, route parameters(used for advanced query building). To display our grid, add the following code to the template:

{% import '@OroDataGrid/macros.html.twig' as dataGrid %}
{% block content %}
     {{ dataGrid.renderGrid('acme-demo-datagrid') }}
{% endblock %}


If your template extends the @OroUI/actions/index.html.twig template, macros will be already imported, and you only have to set the gridName variable to get the grid rendered

Advanced Configuration

Actions, mass actions, toolbar, pagers, grid views and other functionality are explained on advanced grid configuration page or you can check configuration reference.


Behavior Customization

To customize the datagrid (e.g., dynamically added columns, custom actions, add additional data, etc.), you can listen to one of the events dispatched in the datagrid component. More information on events, including their full list, is available in the section on events.


The grid can be extended in several ways:

  • create a custom datasource, if needed (e.g., already implemented SearchDatasource for working with a search engine)
  • create a custom extension
  • create some add-ons to the already registered extensions (e.g., a specific backend formatter)
  • change the base datagrid or the base acceptor class (they are passed to the builder as DIC parameters)

Related Articles