Consolidate DataGrid builder paths: datagrid keyword vs pluggablewidget engine

[ako]

DataGrid (com.mendix.widget.web.datagrid.Datagrid) is constructed by two disjoint code paths today. They share the embedded template (sdk/widgets/templates/mendix-11.6/datagrid.json) and produce the same $Type, but the BSON construction is independent — bugs fixed in one path don't fix the other (cf. #64, which only affected the engine path because datagrid_builder.go has its own setAttributeRef helper at line 776).

Current dispatch

mdl/executor/cmd_pages_builder_v3.go:271:

MDL form	Routes to	Builder
datagrid dg (...) { column ... }	buildDataGridV3 → widgetBackend.BuildDataGrid2Widget	mdl/backend/mpr/datagrid_builder.go (1467 lines)
pluggablewidget 'com.mendix.widget.web.datagrid.Datagrid' dg (...) { column ... }	pluggableEngine.Build(def, w)	mdl/executor/widget_engine.go + mdl/backend/mpr/widget_builder.go (also serves every other pluggable widget)

Feature drift

The keyword path implements DataGrid-specific routing that the generic engine doesn't:

Feature	Keyword (datagrid)	Engine (pluggablewidget)
Columns with Attribute:	✓	✓ (since #64 fix)
Per-column Caption: with CaptionParams: placeholders	✓ resolves ClientTemplateParameter for {1}/{2}	⚠ TextTemplate operation works but no caption-params resolver in the engine
Custom-content columns (column ... { dynamictext … })	✓ via DataGridColumnSpec.ChildWidgets → customContent	✗ engine doesn't promote children to a customContent slot
Per-column filter widget	✓ via DataGridColumnSpec.FilterWidget	✗ no per-column filter routing
CONTROLBAR { … } (filtersPlaceholder)	✓ via HeaderWidgets	✗ engine treats controlbar as a generic child — no routing to filtersPlaceholder
CE0463 patches (AllowUpload, property ordering, ClientTemplate translations, boolean defaults)	✓ hand-coded patches	⚠ partially via embedded template; some only apply to the keyword path

The engine path is the only path for every other pluggable widget (Accordion, Maps, AreaChart, etc.). For DataGrid specifically it's a strict subset of the keyword path's feature set.

Why consolidate

1. Bug fixes land in two places. The Generate Overview Page - DataGrid 2 is not up to date #64 fix to setAttributeRefField would have been one-liner across both paths had they shared a helper; today the keyword path's setAttributeRef had to be replicated correctly when the engine equivalent was first written.
2. Schema evolution. New .def.json fields (propertyVisibility[] per Widget property conditional visibility from editorConfig.js (CE0463 on VideoPlayer + Timeline) #574, objectLists[] per v0.10.0 Phase 1: object-list support in pluggable widget engine #538) only feed the engine path. The keyword path either ignores them or needs hand-porting.
3. Test coverage gap. Integration fixtures (mdl-examples/doctype-tests/31-pluggable-datagrid-gallery-v010-examples.mdl) only exercise the keyword form, so the engine path regressed undetected until a user reported it (Generate Overview Page - DataGrid 2 is not up to date #64).
4. 1467 + 1149 lines of split logic for one widget plus the catalogue — collapsing the keyword path into the engine would be one of the largest single simplifications in mdl/backend/mpr/.

Proposed approach

Phase the move so each step is independently mergeable and reversible:

1. Port CONTROLBAR routing into the engine — recognize controlbar as the parent's filtersPlaceholder slot when the parent is com.mendix.widget.web.datagrid.Datagrid. New .def.json field headerSlots[] lets the engine route a child keyword to a named container property. (Generic: also fixes Gallery filter bars.)
2. Port custom-content columns — when an object-list item carries child widgets, promote them to the item's customContent / template sub-property. Today's engine drops them; the keyword path treats ChildWidgets as a first-class column attribute.
3. Port per-column filter routing — extend the engine's object-list dispatch to recognize a nested filter { textfilter … } block as filling the column's filter sub-property slot.
4. Port the keyword's CE0463 patches — fold the AllowUpload / property-ordering / ClientTemplate / boolean-default fixes into the embedded template plus the engine's serialization path so they apply to every widget that reads the same template.
5. Switch the dispatch — once feature parity is reached, route datagrid to pluggableEngine.Build (re-using widget ID com.mendix.widget.web.datagrid.Datagrid from the keyword) and delete datagrid_builder.go.

After Phase 5, the only DataGrid-specific code that should remain is the embedded template plus any per-widget propertyVisibility[] rules generated by #574.

Test plan

• Existing fixture mdl-examples/doctype-tests/31-pluggable-datagrid-gallery-v010-examples.mdl should continue to pass mx check at zero errors after each phase.
• Add a parallel mdl-examples/doctype-tests/31b-pluggablewidget-datagrid-examples.mdl that mirrors fixture 31 but uses pluggablewidget form throughout. Both must pass.
• Roundtrip: describe of a DataGrid built by either path should produce equivalent MDL when re-executed.

Related

• Generate Overview Page - DataGrid 2 is not up to date #64 — the immediate trigger (engine-path AttributeRef bug that the keyword path was immune to)
• v0.10.0 Phase 1: object-list support in pluggable widget engine #538 — object-list keyword support (engine-path feature that the keyword path predates)
• Widget property conditional visibility from editorConfig.js (CE0463 on VideoPlayer + Timeline) #574 — propertyVisibility[] (engine-path schema extension; harder to retrofit into the keyword path)
• v0.10.0 Phase 2: native vs pluggable DATAGRID dispatch + LEGACYDATAGRID keyword #539 — dual-stack keyword dispatch (related editorial policy: LEGACYDATAGRID for native, DATAGRID for pluggable)

[github-actions]

Issue Triage

Summary:
The issue proposes consolidating the two separate code paths that build the Mendix DataGrid widget (the datagrid keyword builder and the generic pluggable‑widget engine) into a single engine‑based implementation, outlining a phased approach to achieve feature parity and reduce duplication.

Checklist for feature request

Required info	Present?	Notes
Use case – why the feature is needed, what problem it solves	✅	Detailed motivations (bug‑fix duplication, schema evolution, test gaps, code size) are provided.
Proposed syntax or behavior (if applicable)	✅	The phased approach describes the desired behavior changes (CONTROLBAR routing, custom‑content columns, filter routing, CE0463 patches, dispatch switch).
Mendix version relevance (if version‑specific)	❌	No explicit mention of which Mendix versions the change targets or any version‑specific constraints.

Missing information
Could you please clarify the Mendix version(s) this feature request pertains to (e.g., does it apply to all supported versions, or is it specific to a certain Mendix release line)? This helps reviewers assess impact and prioritize the work.

Thank you for the thorough proposal! Once the version relevance is added, the issue will be complete.

---

Automated triage via OpenRouter — workflow source

[ako]

Duplicate of #529 Phase 4 ("Native/pluggable dispatch + object lists") in the Unified Schema Registry plan, which already covers consolidating the static keyword builders into thin wrappers over the registry-driven engine. The five-phase breakdown here lands inside that umbrella.

The #64 fix that prompted this issue (engine-path AttributeRef bug) is now documented as a concrete motivating case for Phase 4 — tracking under #529.