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.

Parameter Binding

Parameter binding is used to fill datasource with parameters from datagrid. For example, ORM datasource is working on top of Doctrine ORM and using QueryBuilder to build query to database. Using parameter binding option in orm datasource you can configure mapping between parameters of datagrid and parameters of query.

Configuration Syntax

 1 datagrids:
 2     acme-demo-datagrid:
 3         source:
 4             type: orm
 5             query:
 6                 select:
 7                     - u
 8                 from:
 9                     { table: AcmeDemoBundle:User, alias:u }
10                 where:
11                     and:
12                         - u.group = :group_id
13             bind_parameters:
14                 # Get parameter "group_id" from datagrid
15                 # and set it's value to "group_id" parameter in datasource query
16                 - group_id

If the name of parameters in the grid and the query do not match, you can pass an associative array of parameters, where the key is the name of the parameter in the query, and the value is the name of the parameter of the grid:

 1 datagrids:
 2     acme-demo-grid:
 3         source:
 4             type: orm
 5             query:
 6                 select:
 7                     - u
 8                 from:
 9                     { table: AcmeDemoBundle:User, alias:u }
10                 where:
11                     and:
12                         - u.group = :group_id
13             bind_parameters:
14                 # Get parameter "groupId" from datagrid
15                 # and set it's value to "group_id" parameter in datasource query
16                 group_id: groupId

To pass parameter groupId to the grid, use the following format when rendering the grid in the template:

1{{ dataGrid.renderGrid('acme-demo-datagrid', {'groupId': entityId}) }}

Or pass them directly to DatagridManager.

1$datagridManager->getDatagrid('acme-demo-datagrid', ['groupId' => $entityId]);

The full format for declaring parameters binding is also available:

1 bind_parameters:
2     data_in: # option string key will be interpreted as name of parameter in query
3         path: _parameters.groupId # it will reference to parameter groupId in key _parameters of parameter bag.
4         default: [0] # some default value, will be used if parameter is not passed
5         type: array # type applicable with Doctrine: Doctrine\DBAL\Types\Type::getType()
1 bind_parameters:
2     -
3         name: # name of parameter in query
4         path: _parameters.groupId # it will reference to parameter groupId in key _parameters of parameter bag.
5         default: [0] # some default value, will be used if parameter is not passed
6         type: array # type applicable with Doctrine: Doctrine\DBAL\Types\Type::getType()

Support of Parameter Binding by Datasource

Datasource must implement ParameterBinderAwareInterface to support the bind_parameters option.

Parameter Binder Class

Parameter binder class must implements ParameterBinderInterface and depends on datasources implementation.

Example of usage:

1 // get parameter "name" from datagrid parameter bag and add it to datasource
2 $queryParameterBinder->bindParameters($datagrid, ['name']);
3
4 // get parameter "id" from datagrid parameter bag and add it to datasource as parameter "client_id"
5 $queryParameterBinder->bindParameters($datagrid, ['client_id' => 'id']);
6
7 // get parameter "email" from datagrid parameter bag and add it to datasource, all other existing
8 // parameters will be cleared
9 $queryParameterBinder->bindParameters($datagrid, ['email'], false);

Parameter Binding Listener

DatasourceBindParametersListener is responsible for running the binding of the datasource parameters. It checks whether the datasource implements ParameterBinderInterface and whether it has the bind_parameters option.

If the grid configuration is applicable, then parameters configuration specified in the bind_parameters is passed to the datasource method bindParameters.