Context engineering: IMAGE widget skill docs missing datasource/imageUrl properties

[engalar]

Problem

The create-page.md skill documentation for IMAGE widget only documents dimension properties:

IMAGE imgLogo (Width: 200, Height: 100)

It completely omits the most important properties: datasource, imageUrl, imageIcon. This causes AI agents to incorrectly conclude that "IMAGE source must be configured manually in Studio Pro" — wasting human effort on something mxcli can do.

Root Cause Chain

1. create-page.md treats IMAGE as a "simple shorthand widget" with only Width/Height
2. AI reads this doc, finds no source-setting syntax → assumes it doesn't exist
3. AI tells user "needs Studio Pro manual step"
4. User challenges the claim → AI investigates → discovers PLUGGABLEWIDGET syntax works:

PLUGGABLEWIDGET 'com.mendix.widget.web.image.Image' imgLogo (
  datasource: imageUrl,
  imageUrl: 'img/logo_dark.svg',
  widthUnit: pixels, width: 48,
  heightUnit: pixels, height: 48
)

5. Also works via ALTER PAGE + REPLACE to update existing IMAGE widgets

Proposal

1. Enhance IMAGE section in create-page.md

Add datasource modes and key properties:

### IMAGE Widget — Setting Image Source

IMAGE widgets support three source modes via PLUGGABLEWIDGET syntax:

| Mode | Property | Use Case |
|------|----------|----------|
| `datasource: image` | `imageObject` | Dynamic image from entity (default) |
| `datasource: imageUrl` | `imageUrl: 'path'` | Static image from URL or file path |
| `datasource: icon` | `imageIcon` | Icon-based image |

**Static image from file (most common for logos/branding):**
```sql
PLUGGABLEWIDGET 'com.mendix.widget.web.image.Image' imgLogo (
  datasource: imageUrl,
  imageUrl: 'img/logo.svg',
  widthUnit: pixels, width: 48,
  heightUnit: pixels, height: 48
)

Note: For theme images, use paths relative to theme/web/ (e.g., img/logo.svg → theme/web/img/logo.svg).

### 2. Add cross-reference to `mxcli widget docs`

In `create-page.md`, add a tip:

```markdown
> **Tip:** Run `mxcli widget docs -p app.mpr` to generate complete property documentation
> for all pluggable widgets. Output is saved to `.ai-context/skills/widgets/`.
> When unsure about widget properties, check these generated docs before assuming
> a feature requires Studio Pro.

3. General principle for all shorthand widgets

Add a note that ALL shorthand widgets (IMAGE, COMBOBOX, GALLERY, etc.) are pluggable widgets under the hood and can always fall back to full PLUGGABLEWIDGET syntax for advanced properties not covered by the shorthand.

Impact

Without this fix, AI agents will continue to:

• Tell users that image sources "need Studio Pro"
• Miss the PLUGGABLEWIDGET escape hatch for advanced widget configuration
• Underutilize the full widget property surface that mxcli actually supports

Evidence

Successfully used in Carrefour PoC project — set Carrefour logo on 6 pages entirely via MDL, zero Studio Pro intervention:

ALTER PAGE OrderManagement.Home_Web {
  REPLACE imgLogo WITH {
    PLUGGABLEWIDGET 'com.mendix.widget.web.image.Image' imgLogo (
      datasource: imageUrl, imageUrl: 'img/logo_dark.svg',
      widthUnit: pixels, width: 48, heightUnit: pixels, height: 48
    )
  }
};

[github-actions]

Issue Triage

Summary:
The issue requests improved documentation for the IMAGE widget in create-page.md to include datasource properties and clarify that IMAGE widgets can be fully configured via PLUGGABLEWIDGET syntax, preventing AI agents from incorrectly assuming manual Studio Pro steps are needed.

Checklist for feature request:

• ✅ Use case – explains why the feature is needed (AI agents miss source‑setting syntax, leading to unnecessary manual work).
• ✅ Proposed syntax or behavior – provides concrete Markdown additions, example PLUGGABLEWIDGET snippets, and a tip about mxcli widget docs.
• ⚪ Mendix version relevance – not indicated as version‑specific; the request appears applicable across versions, so this field is optional.

Conclusion:
The issue contains the essential information for a feature request. Thank you for the clear proposal and evidence! If you later discover that the change only applies to certain Mendix releases, feel free to add that detail. Otherwise, we can move forward with the enhancement.

---

Automated triage via OpenRouter — workflow source

[ako]

Fixed in commit ea871a9. Updated .claude/skills/mendix/create-page.md with:

1. IMAGE datasource modes — table showing datasource: image | imageUrl | icon with corresponding properties and use cases
2. PLUGGABLEWIDGET syntax examples — full examples for setting image source via imageUrl, plus ALTER PAGE for updating existing images
3. PLUGGABLEWIDGET escape hatch section — general note at the end of the skill file explaining that ALL shorthand widgets (IMAGE, COMBOBOX, GALLERY, etc.) can fall back to PLUGGABLEWIDGET 'widget.id' syntax for full property access
4. mxcli widget docs tip — reference to generated widget property documentation

AI agents reading the updated skill will now know how to set image sources without suggesting manual Studio Pro steps.