Important

You are browsing upcoming documentation for version 6.0 of OroCommerce, OroCRM, and OroPlatform, scheduled for release in 2024. 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.

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:

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

Datasource 

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:

datagrids:
    acme-demo-datagrid:
        source:
            type: orm  # datasource type
            query:
                ....   # 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')
            ->select('u')
            // ->where(...)
            // ->join(...)
            // ->orderBy(...)
        ;
    }
}

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

datagrids:
    acme-demo-datagrid:
        source:
            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

datagrids:
    acme-demo-datagrid:
        source:
            type: orm
            query:
                select:
                    - u
                from:
                    { table: Acme\Bundle\DemoBundle\Entity\User, alias:u }
            where:
                and:
                    - u.group = :group_id
            bind_parameters:
                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.

Note

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).

Note

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:

datagrids:
    acme-demo-datagrid:
        source:
            type: orm
            query:
                select: [ o.firstName, o.lastName, o.age ]
                from:
                    - { 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
        columns:
            firstName:                                   # data identifier will be taken from column name
                label: acme.demo.grid.columns.firstName  # translation string
            lastName:
                label: acme.demo.grid.columns.firstName  # translation string
            age:
                label: acme.demo.grid.columns.age        # translation string
                frontend_type: number                    # needed for correct l10n (e.g. thousand, decimal separators etc)

Sorting 

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:

datagrids:
    acme-demo-datagrid:
        ...                                 # definition from previous examples
        sorters:
            columns:
                firstName:
                    data_name: o.firstName
                lastName:
                    data_name: o.lastName
                age:
                    data_name: o.age
            default:
                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 %}

Note

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.

Extendability 

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.

Extending 

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