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.

Selected Fields Providers 

The selected fields providers must implement interface Oro\Bundle\DataGridBundle\Provider\SelectedFields\SelectedFieldsProviderInterface. Selected fields provider returns an array of field names which must be present in the select statement of the datasource query according to the given datagrid configuration and parameters. In other words, depending on the datagrid configuration and parameters (request- and user-specific), it must return the fields needed to be displayed/processed for the datagrid to be rendered correctly.

Keep in mind that the word field here does not mean an entity field or extended field, but rather a field that must be present in the select statement of a query.

OroDatagridBundle provides two selected fields providers out-of-box:

  • oro_datagrid.provider.selected_fields.columns (Oro\Bundle\DataGridBundle\Provider\SelectedFields\SelectedFieldsFromColumnsProvider)

  • oro_datagrid.provider.selected_fields.sorters (Oro\Bundle\DataGridBundle\Provider\SelectedFields\SelectedFieldsFromSortersProvider)

These providers are collected in the oro_datagrid.provider.selected_fields (Oro\Bundle\DataGridBundle\Provider\SelectedFields\SelectedFieldsProvider) service, which calls all its inner providers and returns an array of unique field names.

How to Use 

Selected fields providers enable fetching field names which must be present in the datasource query of the datagrid. This data can be used in datagrid extensions which modify the datagrid configuration, add new columns, sorters, etc. The purpose is to detect whether it is necessary to add a certain field or join the datasource query, as not every field added to the query is actually displayed to the end user. This can significantly help improve the performance of datagrids that work with tables with many records.

For example, the oro_datagrid.provider.selected_fields service is used in the oro_entity_extend.datagrid.extension.dynamic_fields datagrid extension to prevent adding joins for extended fields which are not going to be displayed to the end user.

Selected Fields Provider 

The Oro\Bundle\DataGridBundle\Provider\SelectedFields\SelectedFieldsProvider composite provider is declared as the oro_datagrid.provider.selected_fields service that returns selected fields from all inner providers.

Example:

$selectedFieldsStateProvider = $this->container->get('oro_datagrid.provider.selected_fields');
$selectedFields = $selectedFieldsStateProvider->getSelectedFields($datagridConfiguration, $datagridParameters);
var_export($selectedFields);
// Will output
//['sampleField1', 'sampleColumn2']

Fields Required by Columns 

The Oro\Bundle\DataGridBundle\Provider\SelectedFields\SelectedFieldsFromColumnsProvider provider is declared as the oro_datagrid.provider.selected_fields.columns service. It returns fields (used in renderable columns) that must be present in the select statement of the datasource query.

It uses Oro\Bundle\DataGridBundle\Provider\State\ColumnsStateProvider to fetch the current state of columns, then collects data_name configuration options from columns which are currently renderable (visible).

Keep in mind that the resulting array of fields can differ depending on the moment when the provider is called because it fetches data from the datagrid configuration and state, which can be changed by extensions and listeners.

The oro_datagrid.provider.selected_fields.columns service is not intended to be used directly. Use the oro_datagrid.provider.selected_fields service instead to get a full list of selected fields. However, you can use it if you specifically need those fields that are used in renderable columns.

Fields Required by Sorters 

The Oro\Bundle\DataGridBundle\Provider\SelectedFields\SelectedFieldsFromSortersProvider provider is declared as a oro_datagrid.provider.selected_fields.sorters service. It returns an array of field names (required by applied sorters) which must be present in the select statement of the datasource query.

It uses Oro\Bundle\DataGridBundle\Provider\State\SortersStateProvider to fetch the current state of sorters, then collects data_name configuration options from sorters that are currently applied.

Keep in mind that the resulting array of fields can differ depending on the moment when a provider is called because it fetches data from the datagrid configuration and state that can be changed by extensions and listeners.

The oro_datagrid.provider.selected_fields.sorters service is not intended to be used directly. Use oro_datagrid.provider.selected_fields service instead to get a full list of selected fields. However, you can use it if you specifically need those fields that are required by applied sorters.

How to Customize 

You can create your own selected fields provider by implementing Oro\Bundle\DataGridBundle\Provider\SelectedFields\SelectedFieldsProviderInterface. Define it as a service with the oro_datagrid.selected_fields_provider tag.