feat: add full roundtrip for pluggable Image widget (com.mendix.widget.web.image.Image)

Implement DESCRIBE → CREATE roundtrip for the pluggable React-based Image
widget, which is the most-used pluggable widget (784 instances across test
projects). The IMAGE keyword now routes to the pluggable engine instead of
the built-in Forms$StaticImageViewer (use STATICIMAGE for the built-in).

- Add image.json template with all 21 properties from the widget XML definition
- Add image.def.json with property mappings for the pluggable engine
- Add opTextTemplate and opAction operations to the widget engine
- Add OnClick source resolver for AST action → serialized BSON
- Export SerializeClientAction for use by the pluggable engine
- Add DESCRIBE extraction: extractImageProperties, extractCustomWidgetPropertyTextTemplate,
  extractCustomWidgetPropertyAction helpers
- Add IMAGE output formatting in DESCRIBE with non-default property suppression
- Re-route IMAGE keyword to pluggable engine; STATICIMAGE/DYNAMICIMAGE unchanged
- Update docs: custom-widgets.md skill and engine design doc

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ako

.claude/skills/mendix/custom-widgets.md

@@ -221,6 +221,8 @@ Modes are evaluated in definition order -- first match wins. A mode with no `con
 | `datasource` | Sets `Value.DataSource` (serialized BSON) | `DataSource` |
 | `selection` | Sets `Value.Selection` (mode string) | `Selection` |
 | `widgets` | Replaces `Value.Widgets` array with child widget BSON | child slot |
+| `texttemplate` | Sets text in `Value.TextTemplate` (Forms$ClientTemplate) | property name (resolved as string) |
+| `action` | Sets `Value.Action` with serialized client action BSON | `OnClick` (resolved from AST Action) |
 
 ### Mapping Order Constraints
 

docs/plans/2026-03-25-pluggable-widget-engine-design.md

@@ -143,6 +143,8 @@ All existing pluggable widget builders use combinations of these 6 operations:
 | `datasource` | `setDataSource()` | `source` → MDL DataSource prop | Builds and sets `DataSource` object |
 | `selection` | `setSelectionMode()` | `value` or `source` | Set widget selection mode (Single/Multi) |
 | `widgets` | inline child BSON | `childSlots` config | Embeds serialized child widgets into `Widgets` array |
+| `texttemplate` | `setTextTemplateValue()` | `source` → string prop | Sets text in `TextTemplate` (Forms$ClientTemplate) |
+| `action` | `SerializeClientAction()` | `OnClick` → AST Action | Sets `Action` with serialized client action BSON |
 
 Operations are registered in an `OperationRegistry` and new types can be added without modifying the engine.
 
@@ -198,7 +200,7 @@ Therefore, in any mode that uses both, **`datasource` must come before `associat
 
 ### Operation Validation
 
-Operation names in `.def.json` files are validated at load time against the 6 known operations: `attribute`, `association`, `primitive`, `selection`, `datasource`, `widgets`. Invalid operation names produce an error when `NewWidgetRegistry()` or `LoadUserDefinitions()` runs, rather than failing silently at build time.
+Operation names in `.def.json` files are validated at load time against the 8 known operations: `attribute`, `association`, `primitive`, `selection`, `datasource`, `widgets`, `texttemplate`, `action`. Invalid operation names produce an error when `NewWidgetRegistry()` or `LoadUserDefinitions()` runs, rather than failing silently at build time.
 
 ### Mode Selection Conditions
 

mdl/executor/cmd_pages_builder_v3.go

@@ -319,10 +319,20 @@ func (pb *pageBuilder) buildWidgetV3(w *ast.WidgetV3) (pages.Widget, error) {
 		widget, err = pb.buildDropdownFilterV3(w)
 	case "DATEFILTER":
 		widget, err = pb.buildDateFilterV3(w)
-	case "IMAGE", "STATICIMAGE":
+	case "STATICIMAGE":
 		widget, err = pb.buildStaticImageV3(w)
 	case "DYNAMICIMAGE":
 		widget, err = pb.buildDynamicImageV3(w)
+	case "IMAGE":
+		// IMAGE routes to the pluggable React widget (com.mendix.widget.web.image.Image)
+		pb.initPluggableEngine()
+		if pb.widgetRegistry != nil {
+			if def, ok := pb.widgetRegistry.Get("IMAGE"); ok {
+				return pb.pluggableEngine.Build(def, w)
+			}
+		}
+		// Fallback to static image if pluggable engine unavailable
+		widget, err = pb.buildStaticImageV3(w)
 	default:
 		// Try pluggable widget engine for registered widget types
 		pb.initPluggableEngine()

mdl/executor/cmd_pages_describe.go

@@ -531,6 +531,17 @@ type rawWidget struct {
 	EditableIf string // Expression from ConditionalEditabilitySettings
 	// Design properties from Appearance
 	DesignProperties []rawDesignProp
+	// Pluggable Image widget properties
+	ImageUrl        string // Image URL (from textTemplate)
+	AlternativeText string // Alt text (from textTemplate)
+	ImageWidth      string // Width in pixels/percentage
+	ImageHeight     string // Height in pixels/percentage
+	WidthUnit       string // "auto", "pixels", "percentage"
+	HeightUnit      string // "auto", "pixels", "percentage", "viewport"
+	DisplayAs       string // "fullImage", "thumbnail"
+	Responsive      string // "true", "false"
+	ImageType       string // "image", "imageUrl", "icon"
+	OnClickType     string // "action", "enlarge"
 }
 
 // rawDesignProp represents a parsed design property from BSON.

mdl/executor/cmd_pages_describe_output.go

@@ -461,6 +461,45 @@ func (e *Executor) outputWidgetMDLV3(w rawWidget, indent int) {
 			} else {
 				formatWidgetProps(e.output, prefix, header, props, "\n")
 			}
+		} else if widgetType == "IMAGE" {
+			header := fmt.Sprintf("IMAGE %s", w.Name)
+			props := []string{}
+			if w.ImageType != "" && w.ImageType != "image" {
+				props = append(props, fmt.Sprintf("ImageType: %s", w.ImageType))
+			}
+			if w.ImageUrl != "" {
+				props = append(props, fmt.Sprintf("ImageUrl: %s", mdlQuote(w.ImageUrl)))
+			}
+			if w.AlternativeText != "" {
+				props = append(props, fmt.Sprintf("AlternativeText: %s", mdlQuote(w.AlternativeText)))
+			}
+			if w.WidthUnit != "" && w.WidthUnit != "auto" {
+				props = append(props, fmt.Sprintf("WidthUnit: %s", w.WidthUnit))
+			}
+			if w.ImageWidth != "" && w.ImageWidth != "100" {
+				props = append(props, fmt.Sprintf("Width: %s", w.ImageWidth))
+			}
+			if w.HeightUnit != "" && w.HeightUnit != "auto" {
+				props = append(props, fmt.Sprintf("HeightUnit: %s", w.HeightUnit))
+			}
+			if w.ImageHeight != "" && w.ImageHeight != "100" {
+				props = append(props, fmt.Sprintf("Height: %s", w.ImageHeight))
+			}
+			if w.DisplayAs != "" && w.DisplayAs != "fullImage" {
+				props = append(props, fmt.Sprintf("DisplayAs: %s", w.DisplayAs))
+			}
+			if w.Responsive != "" && w.Responsive != "true" {
+				props = append(props, fmt.Sprintf("Responsive: %s", w.Responsive))
+			}
+			if w.OnClickType == "enlarge" {
+				props = append(props, "OnClickType: enlarge")
+			}
+			if w.Action != "" {
+				props = append(props, fmt.Sprintf("OnClick: %s", w.Action))
+			}
+			props = appendConditionalProps(props, w)
+			props = appendAppearanceProps(props, w)
+			formatWidgetProps(e.output, prefix, header, props, "\n")
 		} else {
 			header := fmt.Sprintf("%s %s", widgetType, w.Name)
 			props := []string{}

mdl/executor/cmd_pages_describe_parse.go

@@ -195,6 +195,10 @@ func (e *Executor) parseRawWidget(w map[string]any) []rawWidget {
 			widget.FilterAttributes = e.extractFilterAttributes(w)
 			widget.FilterExpression = e.extractFilterExpression(w)
 		}
+		// For pluggable Image widget, extract image-specific properties
+		if widget.RenderMode == "IMAGE" {
+			e.extractImageProperties(w, &widget)
+		}
 		return []rawWidget{widget}
 
 	case "Forms$Label", "Pages$Label":

mdl/executor/cmd_pages_describe_pluggable.go

@@ -76,6 +76,8 @@ func (e *Executor) extractCustomWidgetType(w map[string]any) string {
 			return "DROPDOWNFILTER"
 		case "com.mendix.widget.web.datagriddatefilter.DatagridDateFilter":
 			return "DATEFILTER"
+		case "com.mendix.widget.web.image.Image":
+			return "IMAGE"
 		default:
 			// Extract last part of widget ID and uppercase it
 			parts := strings.Split(widgetID, ".")
@@ -996,3 +998,117 @@ func (e *Executor) extractCustomWidgetPropertyAttributes(w map[string]any, prope
 	}
 	return nil
 }
+
+// extractImageProperties extracts properties from a pluggable Image CustomWidget.
+func (e *Executor) extractImageProperties(w map[string]any, widget *rawWidget) {
+	widget.ImageType = e.extractCustomWidgetPropertyString(w, "datasource")
+	widget.ImageUrl = e.extractCustomWidgetPropertyTextTemplate(w, "imageUrl")
+	widget.AlternativeText = e.extractCustomWidgetPropertyTextTemplate(w, "alternativeText")
+	widget.ImageWidth = e.extractCustomWidgetPropertyString(w, "width")
+	widget.ImageHeight = e.extractCustomWidgetPropertyString(w, "height")
+	widget.WidthUnit = e.extractCustomWidgetPropertyString(w, "widthUnit")
+	widget.HeightUnit = e.extractCustomWidgetPropertyString(w, "heightUnit")
+	widget.DisplayAs = e.extractCustomWidgetPropertyString(w, "displayAs")
+	widget.Responsive = e.extractCustomWidgetPropertyString(w, "responsive")
+	widget.OnClickType = e.extractCustomWidgetPropertyString(w, "onClickType")
+	widget.Action = e.extractCustomWidgetPropertyAction(w, "onClick")
+}
+
+// extractCustomWidgetPropertyTextTemplate extracts text from a TextTemplate property of a CustomWidget.
+func (e *Executor) extractCustomWidgetPropertyTextTemplate(w map[string]any, propertyKey string) string {
+	obj, ok := w["Object"].(map[string]any)
+	if !ok {
+		return ""
+	}
+
+	propTypeKeyMap := buildPropertyTypeKeyMap(w, false)
+
+	props := getBsonArrayElements(obj["Properties"])
+	for _, prop := range props {
+		propMap, ok := prop.(map[string]any)
+		if !ok {
+			continue
+		}
+		typePointerID := extractBinaryID(propMap["TypePointer"])
+		propKey := propTypeKeyMap[typePointerID]
+		if propKey != propertyKey {
+			continue
+		}
+		value, ok := propMap["Value"].(map[string]any)
+		if !ok {
+			continue
+		}
+		// Extract text from TextTemplate
+		if textTemplate, ok := value["TextTemplate"].(map[string]any); ok && textTemplate != nil {
+			if template, ok := textTemplate["Template"].(map[string]any); ok && template != nil {
+				items := getBsonArrayElements(template["Items"])
+				for _, item := range items {
+					itemMap, ok := item.(map[string]any)
+					if !ok {
+						continue
+					}
+					if text := extractString(itemMap["Text"]); text != "" {
+						return text
+					}
+				}
+			}
+		}
+	}
+	return ""
+}
+
+// extractCustomWidgetPropertyAction extracts an action description from a CustomWidget property.
+// Returns a formatted string like "CALL_MICROFLOW Module.Flow" or "SHOW_PAGE Module.Page".
+func (e *Executor) extractCustomWidgetPropertyAction(w map[string]any, propertyKey string) string {
+	obj, ok := w["Object"].(map[string]any)
+	if !ok {
+		return ""
+	}
+
+	propTypeKeyMap := buildPropertyTypeKeyMap(w, false)
+
+	props := getBsonArrayElements(obj["Properties"])
+	for _, prop := range props {
+		propMap, ok := prop.(map[string]any)
+		if !ok {
+			continue
+		}
+		typePointerID := extractBinaryID(propMap["TypePointer"])
+		propKey := propTypeKeyMap[typePointerID]
+		if propKey != propertyKey {
+			continue
+		}
+		value, ok := propMap["Value"].(map[string]any)
+		if !ok {
+			continue
+		}
+		action, ok := value["Action"].(map[string]any)
+		if !ok || action == nil {
+			continue
+		}
+		actionType := extractString(action["$Type"])
+		switch actionType {
+		case "Forms$MicroflowAction", "Pages$MicroflowClientAction":
+			if settings, ok := action["MicroflowSettings"].(map[string]any); ok {
+				if mf := extractString(settings["Microflow"]); mf != "" {
+					return "CALL_MICROFLOW " + mf
+				}
+			}
+		case "Forms$CallNanoflowClientAction", "Pages$CallNanoflowClientAction":
+			if settings, ok := action["NanoflowSettings"].(map[string]any); ok {
+				if nf := extractString(settings["Nanoflow"]); nf != "" {
+					return "CALL_NANOFLOW " + nf
+				}
+			}
+		case "Forms$FormAction", "Pages$FormAction":
+			if settings, ok := action["PageSettings"].(map[string]any); ok {
+				if page := extractString(settings["Page"]); page != "" {
+					return "SHOW_PAGE " + page
+				}
+			}
+		case "Forms$NoAction", "Pages$NoAction":
+			return ""
+		}
+	}
+	return ""
+}

mdl/executor/theme_reader.go

@@ -120,7 +120,7 @@ var mdlKeywordToDesignPropsKey = map[string]string{
 	"LAYOUTGRID":        "LayoutGrid",
 	"DYNAMICTEXT":       "DynamicText",
 	"STATICTEXT":        "Label",
-	"IMAGE":             "StaticImageViewer",
+	"IMAGE":             "Image",
 	"STATICIMAGE":       "StaticImageViewer",
 	"DYNAMICIMAGE":      "DynamicImageViewer",
 	"NAVIGATIONLIST":    "NavigationList",