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.

Events

Events List

Datagrids in Oro applications are highly customizable. It is possible to modify an existing grid in order to fetch more data than it was originally defined in the grid configuration. In order to provide extendability points, build and result events have been introduced.

Build Events

Build events are dispatched by the Builder class right before and immediately after processing the configuration and building datasource. They are useful in case you need to modify the datagrid or a query configuration.

Four events are dispatched during the build process:

  • Class BuildBefore, event name: oro_datagrid.datagrid.build.before

  • Class BuildBefore, event name: oro_datagrid.datagrid.build.before.DATAGRID_NAME

  • Class BuildAfter, event name: oro_datagrid.datagrid.build.after

  • Class BuildAfter, event name: oro_datagrid.datagrid.build.after.DATAGRID_NAME

BuildBefore Events

By listening to these events, you can add new elements to the grid configuration or modify the already existing configuration in your event listener. You can use the generic build.before event to listen to all or specific datagrids, which will be called only for the given datagrid - build.before.DATAGRID_NAME.

The BuildBefore event class has access to the DatagridConfiguration instance.

Hint

Please note that at this point datasource has not been initialized yet, therefore calling $event->getDatagrid()->getDatasource() returns null.

As an illustration, let’s add one more column to a specific datagrid. For this, create an event listener and modify the existing configuration the following way:

 1 <?php
 2
 3 namespace Acme\Bundle\AcmeBundle\EventListener\Datagrid;
 4
 5 use Oro\Bundle\DataGridBundle\Event\BuildBefore;
 6
 7 class AdditionalColumnDatagridListener
 8 {
 9     /**
10     * @param BuildBefore $event
11     */
12     public function onBuildBefore(BuildBefore $event)
13     {
14         $config = $event->getConfig();
15         $config->offsetSetByPath('[columns][myCustomColumn]', ['label' => 'acme.my_custom_column.label']);
16         $config->offsetAddToArrayByPath('[source][query][select]', ['123 as myCustomColumn']);
17     }
18 }

Once the listener is created, register it in services.yml:

1 acme_bundle.event_listener.datagrid.additional_column:
2     class: Acme\Bundle\AcmeBundle\EventListener\Datagrid\AdditionalColumnDatagridListener
3     tags:
4         - { name: kernel.event_listener, event: oro_datagrid.datagrid.build.before.DATAGRID_NAME, method: onBuildBefore }

Use Cases

  • Add additional columns and update query configuration for the translation datagrid: Oro\Bundle\TranslationBundle\EventListener\Datagrid\LanguageListener

  • Remove public column from the system calendar datagrid: Oro\Bundle\CalendarBundle\EventListener\Datagrid\SystemCalendarGridListener

  • (OroCommerce) Bind user’s currency parameter to the checkout grid: Oro\Bundle\CheckoutBundle\Datagrid\CheckoutGridListener

BuildAfter Events

By listening to these events you can modify the datasource or even the whole datagrid instance. However, the most common case for this event is to modify the query (add additional joins, selects, the where conditions, etc.).

You can use generic build.after event for listening to all or specific datagrids, which will be called only for a given datagrid - build.after.DATAGRID_NAME.

The BuildAfter event class has access to Datagrid instance.

As an example, let us filter the datagrid by a certain value from the request params. For this, create an event listener and modify the query builder, as illustrated below:

 1 <?php
 2
 3 namespace Acme\Bundle\AcmeBundle\EventListener\Datagrid;
 4
 5 use Oro\Bundle\DataGridBundle\Event\BuildAfter;
 6 use Oro\Bundle\DataGridBundle\Datasource\Orm\OrmDatasource;
 7
 8 class FilterByRequestParamListener
 9 {
10     /**
11      * @param BuildAfter $event
12      */
13     public function onBuildAfter(BuildAfter $event)
14     {
15         $datasource = $event->getDatagrid()->getDatasource();
16         if (!$datasource instanceof OrmDatasource) {
17             return;
18         }
19
20         $customFilter = $this->requestStack->getCurrentRequest()->get('custom_filter');
21
22         $queryBuilder = $datasource->getQueryBuilder();
23         $queryBuilder->andWhere($queryBuilder->expr()->eq('some_column', ':custom_filter'));
24         $queryBuilder->setParameter('custom_filter', $customFilter);
25     }
26 }

Please note that this example works only for ORM datasources.

Once the listener is created, register it in services.yml:

1 acme_bundle.event_listener.datagrid.filter_by_request_param:
2 class: Acme\Bundle\AcmeBundle\EventListener\Datagrid\FilterByRequestParamListener
3 tags:
4     - { name: kernel.event_listener, event: oro_datagrid.datagrid.build.after.DATAGRID_NAME, method: onBuildAfter }

Use Cases

  • Apply additional filtering to the activity email grid: Oro\Bundle\EmailBundle\EventListener\Datagrid\ActivityGridListener

  • (OroCommerce) Add additional properties to the storefront product grid: Oro\Bundle\CatalogBundle\EventListener\SearchCategoryFilteringEventListener

Result Events

Result events are type-specific which means that datasource is responsible for dispatching them. Listening to these events is useful both when you need to access a query (e.g., ORM, search) or modify the results.

As an example, have a look at the OrmDatasource. In the getResult() method it dispatches 4 main and 2 additional events:

  • Additional - Class OrmResultBeforeQuery, event name: oro_datagrid.orm_datasource.result.before_query

  • Additional - Class OrmResultBeforeQuery, event name: oro_datagrid.orm_datasource.result.before_query.DATAGRID_NAME

  • Main - Class OrmResultBefore, event name: oro_datagrid.orm_datasource.result.before

  • Main - Class OrmResultBefore, event name: oro_datagrid.orm_datasource.result.before.DATAGRID_NAME

  • Main - Class OrmResultAfter, event name: oro_datagrid.orm_datasource.result.after

  • Main - Class OrmResultAfter, event name: oro_datagrid.orm_datasource.result.after.DATAGRID_NAME

The first four events are mostly used to access a query at different stages, while the last two are used to modify the results.

Remember to dispatch result events when creating your own custom datasource type.

ResultBefore Events

The purpose of these events is to have the ability to access datagrid or a query instance before the datasource starts building the results. You can use generic result.before event for listening to all or specific datagrids, which will be called only for a given datagrid - result.before.DATAGRID_NAME.

Use Cases

  • Apply ACL to a datagrid datasource: Oro\Bundle\DataGridBundle\EventListener\OrmDatasourceAclListener

ResultAfter Events

The purpose of these events is to have ability to modify data after the rows were fetched from the datasource. You can use generic result.after event for listening to all or specific datagrids, which will be called only for a given datagrid - result.after.DATAGRID_NAME.

For instance, if you have complex data that is hard to process with the standard datagrid configuration using YML files, you can create an event listener and fetch the data once the rows are fetched from the datasource.

 1 <?php
 2
 3 namespace Acme\Bundle\AcmeBundle\EventListener\Datagrid;
 4
 5 use Oro\Bundle\DataGridBundle\Event\OrmResultAfter;
 6 use Oro\Bundle\DataGridBundle\Datasource\ResultRecord;
 7
 8 class ComplexDataDatagridListener
 9 {
10     /**
11      * @param OrmResultAfter $event
12      */
13     public function onResultAfter(OrmResultAfter $event)
14     {
15         /** @var ResultRecord[] $records */
16         $records = $event->getRecords();
17
18         $complexData = $this->complexService->getComplexDataForRecords($records);
19
20         foreach ($records as $record) {
21             $recordId = $record->getValue('id');
22             $record->addData(['complexData' => $complexData[$recordId]]);
23         }
24     }
25 }

Once the event listener is created, register it in services.yml:

1 acme_bundle.event_listener.datagrid.complex_data:
2     class: Acme\Bundle\AcmeBundle\EventListener\Datagrid\ComplexDataDatagridListener
3     tags:
4         - { name: kernel.event_listener, event: oro_datagrid.orm_datasource.result.after.DATAGRID_NAME, method: onResultAfter }

Use Cases

  • Translate workflow fields in the email notification grid: Oro\Bundle\WorkflowBundle\Datagrid\EmailNotificationDatagridListener

  • (OroCommerce) Add payment methods to the order grid: Oro\Bundle\OrderBundle\EventListener\OrderDatagridListener