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.

Frontend Datagrid

Oro/datagrid Events

Mediator Events

Datagrid listens on mediator for events:

  • datagrid:setParam:<gridName> - param, value Set additional datagrid parameters

  • datagrid:removeParam:<gridName> - param Remove additional datagrid parameter

  • datagrid:restoreState:<gridName> - columnName, dataField, included, excluded Restore checkboxes state

  • datagrid:restoreChangeset:<gridName> - dataField, changeset Restore select-cells state

  • datagrid:doRefresh:<gridName> Refresh datagrid

  • datagrid:doReset:<gridName> Reset datagrid state

  • datagrid:changeColumnParam:<gridName> - columnName, option, value Sets column option value

DOM Events

Datagrid emits DOM events on its $el element:

  • datagrid:change:<gridName> - model

Datagrid Render

Datagrid provide twig macros for datagrid render.

Usage example:

{% import 'OroDataGridBundle::macros.html.twig' as dataGrid %}
{{ dataGrid.renderGrid(name, params, renderParams) }}

renderParams provide ability to configure grid view.

Usage example:

 1 <script type="text/template" id="row-template-selector">
 2     <b><%= model.label %></b><br/>
 3     <%= model.description %>
 4 </script>
 5
 6 {% set renderParams = {
 7     themeOptions: {
 8         tagName: 'div', #change grid table tags to div
 9         headerHide: true, #hide grid elements, allowed prefixes: header, footer
10         bodyClassName: 'grid-my-body', #change element class name, allowed prefixes: header, headerRow, body, row, footer
11         rowTemplateSelector: '#row-template-selector' #disable standard row renderer by cells and use given template for full row
12     }
13 } %}

Datagrid Settings Manager

Datagrid Settings allows to:

  • show/hide a column or filters

  • change the order of columns

  • save columns state in Grid View.

Datagrid Settings operates with columns’ attributes:

  • renderable show/hide the column/filters (if is not defined the column is shown)

  • order is used to sort only columns in a row

  • required if true the column/filters can not be hidden (but can be ordered)

  • manageable if false the column does not appear in Datagrid Settings (generally is used for system columns such as actions or selectRow)

There’s the option that allows to turn off Datagrid Settings over datagrids.yml configuration:

1 datagrids:
2     my-grid:
3         ...
4         options:
5             toolbarOptions:
6                 datagridSettingsManager: false

Datagrid Widget

Datagrid widget provide ability to render datagrid by name as widget. When datagrid is rendered inside widget it’s rowClickAction will be disabled and replaced with dummy action. This action will trigger grid-row-select event on widget instance with data parameter of next structure:

1 {
2     datagrid: datagridInstance,
3     model: selectedModel
4 }

Usage example:

 1 {% import 'OroUIBundle::macros.html.twig' as UI %}
 2
 3 <div>
 4     {{ oro_widget_render({
 5         'widgetType': 'block',
 6         'url': path('oro_datagrid_widget', {gridName: 'groups-grid'}),
 7         'title': 'User Groups'|trans,
 8         'alias': 'user-groups-widget'
 9     }) }}
10     <div {{ UI.renderPageComponentAttributes({
11         'module': 'your/row-selection/handler',
12         'options': {
13             'alias': 'user-groups-widget'
14         }
15     })></div>
16 </div>

Create js module with the handler definition your/row-selection/handler as shown in example below, don’t forget to add this module to the list of dynamic-imports in jsmodules.yml

 1 import widgetManager from 'oroui/js/widget-manager';
 2
 3 export default function(options) {
 4     widgetManager.getWidgetInstanceByAlias(options.alias, function(widget) {
 5         widget.on('grid-row-select', function(data) {
 6             console.log(data.datagrid);        // datagrid instance
 7             console.log(data.model);           // row data object
 8             console.log(data.model.get('id')); // row attribute
 9         });
10     });
11 };

Grid Customization Through Layouts

Grid can become customizable through option split_to_cells of datagrid block type in the layout configuration file:

1 id: account_users
2 ...
3 blockType: datagrid
4 options:
5     grid_name: frontend-account-account-user-grid
6     split_to_cells: true

Note

By default, grid builds without layouts blocks (split_to_cells: false)

According to split_to_cells option layout tree of the grid will have hierarchy like this:

 1 account_users
 2     account_users_header_row
 3         account_users_header_cell_firstName
 4         account_users_header_cell_lastName
 5         account_users_header_cell_email
 6         account_users_header_cell_enabled
 7         account_users_header_cell_confirmed
 8     account_users_row
 9         account_users_cell_firstName
10             account_users_cell_firstName_value
11         account_users_cell_lastName
12             account_users_cell_lastName_value
13         account_users_cell_email
14             account_users_cell_email_value
15         account_users_cell_enabled
16             account_users_cell_enabled_value
17         account_users_cell_confirmed
18             account_users_cell_confirmed_value

Where account_users is the main block, which corresponds to block id of datagrid type. Block account_users contains two other blocks: account_users_header_row and account_users_row. First responds to the table header, second - table row. In account_users_header_row we can see <block_id>_cell_<column1…N> blocks which corresponds to <th>…</th> HTML structure. Columns column1 … columnN were taken from datagrids.yml config file:

 1 columns:
 2     firstName:
 3         type:      string
 4         data_name: accountUser.firstName
 5     lastName:
 6         type:      string
 7         data_name: accountUser.lastName
 8     email:
 9         type:      string
10         data_name: accountUser.email
11     enabled:
12         type:      boolean
13         data_name: accountUser.enabled
14     confirmed:
15         type:      boolean
16         data_name: accountUser.confirmed

Block account_users_row consists of <block_id>_<column1…N> which corresponds to <td>…</td>. Leaf blocks <block_id>_cell_<column1…N>_value holds cell value for row value.

Just after grid was divided into cells we can manipulate its blocks.

Note

Good choice to investigate grid structure is Layout Developer Toolbar.

For example, we want to hide column email from frontend-account-account-user-grid. Just remove appropriate header and row columns:

1 - '@remove':
2     id: account_users_header_cell_email
3
4 - '@remove':
5     id: account_users_cell_email

In another case, suppose we want make bold content of column firstName. In layout.yml.twig you should create template like this:

1 {% block _account_users_cell_firstName_value_widget %}
2     <b>{{ block_widget(block) }}</b>
3 {% endblock %}

Grid Layout Configuring

Basic settings for layout grid

  1. In layouts/some_theme/layout.yml specify:

 1 layout:
 2     imports:
 3         -
 4             id: datagrid
 5             root: __root
 6
 7     actions:
 8         - '@setOption':
 9             id: __datagrid
10             optionName: grid_name
11             optionValue: frontend-some-grid

  1. In /config/oro/datagrids.yml should be defined:

1 datagrids:
2     frontend-some-grid:
3 ...

As we see in layout.yml, we need to extend generic layout block first. Later defined in OroDataGridBundle (imports directive used). Also we should to specify optionName with grid_name and optionValue with grid identifier value defined in datagrids.yml.

If we open generic layout block for base theme (base/imports/datagrid/layout.yml) we could see other related with datagrid block: datagrid_toolbar:

 1 layout:
 2     imports:
 3          -
 4              id: datagrid_toolbar
 5              root: __root
 6
 7     actions:
 8         - '@addTree':
 9             items:
10                 __datagrid:
11                     blockType: datagrid
12             tree:
13                 __root:
14                     __datagrid: ~

This block is responsible for rendering grid toolbar, and it consists of different blocks like page_size, pagination, sorting, etc. which also customisable using layouts.

Layout Grid Configuration

Through layout directives like visible , @move, @setOption, etc. we can configure grid settings and params on layout level.

For example, we can set block visibility based on some logic using Symfony expression language:

1 layout:
2     actions:
3         - '@add':
4             id: products
5             parentId: page_content
6             blockType: datagrid
7             options:
8                 grid_name: products-grid
9                 visible: '=data["feature"].isFeatureEnabled("product_feature")'

In DataGridBundle/Layout/Block/Type/DatagridType.php defined additional parameters used for grid rendering:

1 'grid_parameters' => [],
2 'grid_render_parameters' => [],
3 'split_to_cells' => false,

Using split_to_cells parameter we can manipulate grid layout on more detailed level - table cells. How to use this param described in Grid customization through ‘split to cells’ option. Other params defined in Twig macros renderGrid (DataGridBundle/Resources/views/macros.html.twig):

  • grid_parameters - parameters need to be passed to grid request

  • grid_render_parameters - render parameters need to be set for grid rendering

Suppose we need to change some parameters that affects grid layouts on Account > Quotes frontend page.

Using Layout Developer Toolbar in developer mode we can quickly find out grid layout identifiers: quotes_datagrid and quotes_datagrid_toolbar. On Build Block view we can see grid_name parameter: frontend-quotes-grid.

Lets change some options for this grid layout.

In SaleBundle/Resources/views/layouts/default/imports/oro_sale_quote_grid/layout.yml we can specify css class that will be used for grid rendering:

1 - '@setOption':
2     id: __datagrid
3     optionName: grid_render_parameters
4     optionValue:
5         cssClass: 'some-css-class'

If we inspect HTML page with grid we see that class atrribute was added to div element: class=”some-css-class”

In order to pass some extra param to grid request lets specify for example web_catalog_id context param:

1 - '@setOption':
2     id: __datagrid
3     optionName: grid_parameters
4     optionValue:
5         web_catalog_id: '=context["web_catalog_id"]'

If we make some actions with grid like sorting, we see that additional request attribute web_catalog_id was added:

...
frontend-quotes-grid[originalRoute]:oro_sale_quote_frontend_index
frontend-quotes-grid[web_catalog_id]:1
appearanceType:grid
frontend-quotes-grid[_pager][_page]:1
frontend-quotes-grid[_pager][_per_page]:25
...

Suppose we want to modify datagrid toolbar. Lets hide block with page size:

- '@setOption':
    id: __datagrid_toolbar_page_size
    optionName: visible
    optionValue: false

After refresh page Page size will be hidden.

Related Articles