From 492cc36d5ec2acfa50d5208803e085dd09840fb0 Mon Sep 17 00:00:00 2001
From: Ylber <ylber.sadiku@mendix.com>
Date: Fri, 24 Apr 2026 17:19:00 +0200
Subject: [PATCH] Document DataGrid2 column name derivation rules and
 TextTemplate read path
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

add troubleshooting section to alter-page.md covering the silent no-op
symptom when column names don't match, and document all three derivation
rules (attribute short name, sanitized caption, col{N} fallback).

add reading TextTemplate section to debug-bson.md Part 10 documenting
the correct TextTemplate → Template → Items traversal path for executor
code, with wrong/correct Go examples. surfaced by issue #116.
---
 .claude/skills/mendix/alter-page.md |  8 ++++++++
 .claude/skills/mendix/debug-bson.md | 22 ++++++++++++++++++++++
 2 files changed, 30 insertions(+)

diff --git a/.claude/skills/mendix/alter-page.md b/.claude/skills/mendix/alter-page.md
index 127b4fda..fb18680f 100644
--- a/.claude/skills/mendix/alter-page.md
+++ b/.claude/skills/mendix/alter-page.md
@@ -150,6 +150,14 @@ REPLACE dgProducts.Description WITH {
 
 To discover column names, run `DESCRIBE PAGE Module.PageName` and look at the COLUMN names inside the DATAGRID.
 
+**Troubleshooting: column operation succeeds but does nothing**
+If an ALTER targeting a DataGrid column completes without error but makes no change, the column name used in the statement didn't match any column. The most common cause is a mismatch between what DESCRIBE shows and what ALTER resolves internally. Derivation rules:
+- Attribute-bound column → short attribute name (last segment after `.`): `Module.Entity.Description` → `Description`
+- Caption-only column → sanitized caption (non-alphanumeric replaced with `_`, leading/trailing `_` trimmed): `"Order Status"` → `Order_Status`
+- Caption with only special chars (e.g. `"---"`) → falls back to `col1`, `col2`, … (1-based index)
+
+If the column name you copied from DESCRIBE still doesn't work, check whether the column has an attribute binding — attribute names take priority over captions.
+
 ### ADD Variables - Add a Page Variable
 
 ```sql
diff --git a/.claude/skills/mendix/debug-bson.md b/.claude/skills/mendix/debug-bson.md
index be7cd950..e626e6b4 100644
--- a/.claude/skills/mendix/debug-bson.md
+++ b/.claude/skills/mendix/debug-bson.md
@@ -540,6 +540,28 @@ After fixing templates:
 2. Run `mx check app.mpr` - should return 0 errors
 3. Open in Studio Pro - widget should load without "Update widget" prompt
 
+### Reading TextTemplate in executor code
+
+Part 10 above covers writing `Forms$ClientTemplate`. The same structure applies when **reading** it in executor code (e.g. `cmd_alter_page.go`, `cmd_pages_describe_output.go`).
+
+The correct traversal is:
+```
+TextTemplate (Forms$ClientTemplate) → Template (Texts$Text) → Items[] → Translation { Text }
+```
+
+**Do not** read `Items` directly off the `TextTemplate` document — that skips the intermediate `Template` node and silently returns an empty slice. Always traverse one level deeper:
+
+```go
+// WRONG — Items is always empty
+items := dGetArrayElements(dGet(tmplDoc, "Items"))
+
+// CORRECT — traverse Template first
+template := dGetDoc(tmplDoc, "Template")
+items := dGetArrayElements(dGet(template, "Items"))
+```
+
+This applies to any executor function that reads column headers, button captions, or any other translatable text stored as `Forms$ClientTemplate`.
+
 ## Related Documentation
 
 - [BSON Mapping Specification](../../docs/05-mdl-specification/10-bson-mapping.md)