oro-datagrid

name	oro-datagrid
description	Use when creating new OroCommerce v6.1 datagrids, adding columns to existing grids, configuring filters, sorters, actions, mass actions, inline editing, or extending core grids (like product-grid, order-grid, customer-grid). Relevant when the user mentions 'create a grid', 'add column', 'grid filter', 'datagrid', 'data table', 'list view', or grid customization in OroCommerce.

OroCommerce v6.1 Datagrid Configuration & Customization

Core File Location

Datagrids live in Resources/config/oro/datagrids.yml within your bundle. Bundle auto-discovery loads these on kernel compilation.

Grid Structure (v6.1 Canonical Example)

datagrids:
    my_grid:
        source:
            type: orm
            query:
                select: [d]
                from: [{ table: Acme\Bundle\DemoBundle\Entity\Document, alias: d }]
        columns:
            id:
                label: ID
            subject:
                label: Subject
        filters:
            columns:
                subject:
                    type: string
                    data_name: d.subject
        sorters:
            columns:
                id:
                    data_name: d.id
            default:
                id: DESC
        actions:
            view:
                type: navigate
                label: View
                icon: eye
                link: acme_demo_document_view
                rowAction: true

Every grid needs: source (ORM query), columns (display), filters (with data_name), sorters (with data_name), and actions.

Column Types

Most common: string, integer, boolean, datetime, currency (requires currency_code option). See references/column-types.md for the full list.

Extending Existing Grids

Never modify core grid YAMLs. Use a BuildBefore event listener to add columns, filters, or modify config programmatically. For related entity data, use onResultAfter to attach data post-fetch instead of adding JOINs.

See references/datagrid-patterns.md for full listener examples (onBuildBefore, onResultAfter), service registration, join patterns, mass actions, and inline editing configuration.

Key Pitfalls

1. Column data_name mismatch — If sorters/filters use data_name: d.subject but the query doesn't have alias d, sorting fails silently. Always verify alias consistency. Check a datagrids.yml with php scripts/check-datagrid-aliases.php <file-or-dir> (repo root) — it flags filters/sorters data_name values whose alias isn't declared in that grid's source.query.from/join.
2. Filter without data_name — Renders in the UI but produces no WHERE clause. Users see the filter but it does nothing.
3. ACL on grid actions is separate from entity ACL — Both acl_resource on mass_actions AND entity-level ACL must pass. Define the resource in acl.yml.

Cache

Datagrids are compiled into the DIC. After YAML changes: php bin/console cache:clear.

See Also

• references/column-types.md — Full column & filter type reference
• references/datagrid-patterns.md — Inline editing, mass actions, listener examples, join patterns, additional pitfalls
• references/v6.1.md — v6.1 specifics, backward compatibility, and troubleshooting