| ← Back to UI Components | ← Back to Table of Contents |
9.3 Dataverse Grid compatibility and reference index
This filename is retained because older documentation and source comments link to it. The maintained implementation guide is 9.1 Dataverse Grid System. Use this page as a compact lookup when reviewing older grid implementations.
Old terminology to current contract
| Older documentation or code | Current approach |
|---|---|
| One template renders the complete grid | dv_grid lazy shell → dv_grid_content → dv_grid_table |
| Controller manually selects frame templates | Prefer renderDataverseGridResponse() when the standard response shape fits |
| Load every association before processing | Use resolveDataverseGridQueryContext() and column dependency metadata for expensive data |
field ambiguously means SQL and display value |
Stable column key plus queryField, renderField, and optional filterQueryField |
| Client feature flags protect data | Policy authorization and applyScope() protect data; flags only shape UI/processing |
| Full table reload after every modal save | Prefer stable row replace/remove; fall back to the -table frame |
| Shared filter-option cache key | TenantAwareCache::tenantScopedKey() in the grid_filter_options cache |
| Separate “saved-view grid” and “system-view grid” implementations | One trait supports saved views, system views, and their coexistence |
Do not copy examples that use gridColumns, modelClass, a one-level frame,
or a template options array. The current required processing keys are
gridKey, gridColumnsClass, baseQuery, tableName, and
defaultSort; the shell takes gridKey, frameId, and dataUrl.
Quick source index
- Processing:
app/src/Controller/DataverseGridTrait.php - Column base:
app/src/KMP/GridColumns/BaseGridColumns.php - Query dependency context:
app/src/KMP/DataverseGridQueryContext.php - View validation:
app/src/KMP/GridViewConfig.php - View persistence:
app/src/Services/GridViewService.php - Grid controller:
app/assets/js/controllers/grid-view-controller.js - Outer shell:
app/templates/element/dv_grid.php - Outer response:
app/templates/element/dv_grid_content.php - Inner response:
app/templates/element/dv_grid_table.php - Toolbar:
app/templates/element/grid_view_toolbar.php - Table/row renderers:
app/templates/element/dataverse_table*.php - Stable row IDs:
app/src/KMP/GridRowDomId.php - Stream responses:
app/src/Controller/TurboResponseTrait.php - PHP tests: search
app/tests/TestCaseand plugin tests forDataverseGrid,GridView, or the owning controller - JavaScript tests: search
app/tests/jsforgrid-view
Column metadata lookup
The renderer and trait currently recognize these main groups:
- identity and presentation:
key,label,type,width,alignment,defaultVisible,required; - operations:
sortable,searchable,filterable,customSortHandler; - query/display mapping:
queryField,renderField,filterQueryField; live dropdowns and saved filters (including expression trees) preferfilterQueryFieldfor ID matching, thenqueryField, then the qualified column key. Keep this mapping identical across full-grid loads, table-frame refreshes, and CSV exports; - filter behavior:
filterType,filterOptions,filterOptionsSource,showInFilterMenu,lockedFilter,skipAutoFilter,customFilterHandler; - interaction:
clickAction,clickActionPermission, row-action and custom renderer metadata; - export:
exportable,exportOnly,exportValue; - conditional data:
requiresContain,requiresFields,requiresComputed.
Concrete *GridColumns.php classes are the best examples because specialized
metadata evolves with the renderer.
Processing option lookup
Feature switches include showAllTab, canAddViews, canFilter,
canExportCsv, showFilterPills, showViewTabs, and
enableColumnPicker. Context and performance options include
lockedFilters, disablePagination, metadataMode, system-view settings,
and the bulk-selection options.
Read the parameter contract immediately above
DataverseGridTrait::processDataverseGrid() before adding a new option.
Document durable additions in 9.1, not by
re-expanding this compatibility page.
Review checklist for a legacy grid
- The base query is authorized and scoped before processing.
gridKeyis stable and unique to the logical grid.- The outer/table frame IDs follow
{frameId}and{frameId}-table. - Saved-view column keys still exist or have an intentional migration path.
- Relations required for render, sort, filter, and export are loaded.
- Embedded context is enforced by the query, not only a locked filter pill.
- PII columns are removed before grid state or export is built.
- Dynamic filter caches are tenant-scoped.
- Sorting, filtering, history/back, empty states, focus, and keyboard behavior have focused coverage.
- Stream row IDs use
GridRowDomIdand fall back safely to a table refresh.