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 the updated information.
See our Release Process documentation for more information on the currently supported and upcoming releases.
Datagrids
Creating a basic datagrid to display the data of all tasks requires three steps:
- Configure the datagrid
- Create a controller and template
- Add a link to the grid to the application menu
Configure the Grid
The datagrid configuration happens in the datagrids.yml
file in the configuration directory of
your bundle and is divided into several sections:
Datasource
The source
option is used to configure a Doctrine query builder that is used to fetch the data
to be displayed in the grid:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | # src/AppBundle/Resources/config/oro/datagrids.yml
datagrids:
app-tasks-grid:
source:
type: orm
query:
select:
- task.id
- task.subject
- task.description
- task.dueDate
- priority.label AS taskPriority
from:
- { table: AppBundle:Task, alias: task }
join:
left:
- { join: task.priority, alias: priority }
|
Displayed Columns
Then, the columns
option needs to be used to configure how which data will be displayed:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | # src/AppBundle/Resources/config/oro/datagrids.yml
datagrids:
app-tasks-grid:
# ...
columns:
id:
label: ID
frontend_type: integer
subject:
label: Subject
description:
label: Description
dueDate:
label: Due Date
frontend_type: datetime
taskPriority:
label: Priority
|
For each column, the frontend_type
option can be used to customize how data will be displayed
(by default, the data will be shown as is).
Column Sorters
Use the sorters
option to define on which columns’ header the user can click to order by the
data:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | # src/AppBundle/Resources/config/oro/datagrids.yml
datagrids:
app-tasks-grid:
# ...
sorters:
columns:
id:
data_name: task.id
subject:
data_name: task.subject
description:
data_name: task.description
dueDate:
data_name: task.dueDate
taskPriority:
data_name: priority.label
default:
dueDate: DESC
|
Each key under sorters.columns
refers to one of the displayed columns. The data_name
option
is the term that will be used as the order by
term in the Doctrine query.
Data Filters
Data filters are UI elements that allow the user to filter the data being displayed in the data
grid. List all the attributes for which a filter should be shown under the filters.columns
key.
To configure the filter for a certain property two options are needed:
type
configures the UI type of the filter. The type of the filter should be chosen based on the
data type of the underlying attribute.
The data_name
denotes the name of the property to filter and will be used as is to modify the
datagrid’s query builder.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | # src/AppBundle/Resources/config/oro/datagrids.yml
datagrids:
app-tasks-grid:
# ...
filters:
columns:
id:
type: number
data_name: task.id
subject:
type: string
data_name: task.subject
description:
type: string
data_name: task.description
dueDate:
type: datetime
data_name: task.dueDate
taskPriority:
type: string
data_name: priority.label
|
Complete Datagrid Configuration
The final datagrid configuration now looks like this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 | # src/AppBundle/Resources/config/oro/datagrids.yml
datagrids:
app-tasks-grid:
source:
type: orm
query:
select:
- task.id
- task.subject
- task.description
- task.dueDate
- priority.label AS taskPriority
from:
- { table: AppBundle:Task, alias: task }
join:
left:
- { join: task.priority, alias: priority }
columns:
id:
label: ID
frontend_type: integer
subject:
label: Subject
description:
label: Description
dueDate:
label: Due Date
frontend_type: datetime
taskPriority:
label: Priority
sorters:
columns:
id:
data_name: task.id
subject:
data_name: task.subject
description:
data_name: task.description
dueDate:
data_name: task.dueDate
taskPriority:
data_name: priority.label
default:
dueDate: DESC
filters:
columns:
id:
type: number
data_name: task.id
subject:
type: string
data_name: task.subject
description:
type: string
data_name: task.description
dueDate:
type: datetime
data_name: task.dueDate
taskPriority:
type: string
data_name: priority.label
|
Create the Controller and View
To make your datagrid accessible you need to create a controller that can be visited by the user which will serve a view that renders the configured datagrid:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | // src/AppBundle/Controller/TaskController.php
namespace AppBundle\Controller;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Template;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
/**
* @Route("/task")
*/
class TaskController extends Controller
{
/**
* @Route("/", name="app_task_index")
* @Template()
*/
public function indexAction()
{
return [];
}
}
|
The view can be very simple if you extend the OroUIBundle:actions:index.html.twig
template:
1 2 3 4 5 | {# src/AppBundle/Resources/views/Task/index.html.twig #}
{% extends 'OroUIBundle:actions:index.html.twig' %}
{% set gridName = 'app-tasks-grid' %}
{% set pageTitle = 'Task' %}
|
You simply need to configure the name of your datagrid and the title you wish to be displayed. Everything else is handled by the base template from the OroUIBundle.
Link to the Action
At last, you need to make the action accessible by creating a menu item:
1 2 3 4 5 6 7 8 9 10 | # src/AppBundle/Resources/config/oro/navigation.yml
menu_config:
items:
task_list:
label: Tasks
route: app_task_index
tree:
application_menu:
children:
task_list: ~
|
Note
application_menu
is just the name of the menu you want to hook your item into. In this
case, application_menu
is an existing menu that is part of OroPlatform.
Key Classes
Datagrid\Manager
- responsible of preparing the grid and its configuration.Datagrid\Builder
- responsible for creating and configuring the datagrid object and its datasource. Contains registered datasource type and extensions, also it performs check for datasource availability according to ACLDatagrid\Datagrid
- the main grid object, has knowledge ONLY about the datasource object and the interaction with it, all further modifications of the results and metadata come from the extensions ExtensionAcceptor - is a visitable mediator, contains all applied extensions and provokes visits at different points of the interactions.Extension\ExtensionVisitorInterface
- visitor interfaceExtension\AbstractExtension
- basic empty implementationDatasource\DatasourceInterface
- link object between data and grid. Should provide results as array of ResultRecordInterface compatible objectsProvider\SystemAwareResolver
- resolves specific grid YAML syntax expressions. For more information, see the references in configuration topic.
Mixin
Mixin is a datagrid that contains additional (common) information for use by other datagrids.
Configuration Syntax
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | datagrids:
# configuration mixin with column, sorter and filter for an entity identifier
acme-demo-common-identifier-datagrid-mixin:
source:
type: orm
query:
select:
# alias that will be replaced by an alias of the root entity
- __root_entity__.id as identifier
columns:
identifier:
frontend_type: integer
sorters:
data_name: identifier
filters:
columns:
identifier:
type: number
data_name: identifier
acme-demo-user-datagrid:
# one or several mixins
mixins:
- acme-demo-datagrid-mixin
- ...
- ...
source:
type: orm
query:
from:
{ table: AcmeDemoBundle:User, alias:u }
|
Related Articles