pitfall 12

Author: devinea

packages/fiori-docs-embeddings/data_local/fiori_extension_instructions.md

@@ -15,7 +15,7 @@ Replace all placeholder names with your actual values:
 
 ---
 
-**CRITICAL PITFALL 1 — Do NOT use `sap.fe.macros.Form` or `sap.fe.macros.FormElement` inside a standalone `sap.m.Dialog`**: These building blocks require the Fiori Elements page infrastructure (`__EntityControl`, template preprocessing) to function. When placed inside a `sap.m.Dialog` loaded via `Fragment.load()`, they render empty — no fields appear and no error is thrown. Use `sap.ui.layout.form.SimpleForm` with plain `sap.m.Label` and `sap.m.Text` controls instead. This is the only approach that works in a manually loaded fragment dialog.
+**CRITICAL PITFALL 1 — Prefer `sap.ui.layout.form.SimpleForm` over `sap.fe.macros.Form`/`sap.fe.macros.FormElement` for a standalone `sap.m.Dialog`**: SimpleForm with plain `sap.m.Label` and `sap.m.Text` is simpler, has no annotation dependencies, and is the most reliable approach for manually loaded fragment dialogs. `sap.fe.macros.Form` and `sap.fe.macros.FormElement` CAN work inside a `sap.m.Dialog` loaded via `Fragment.load()`, but require several specific conditions all to be met simultaneously (see Pitfalls 9–12): a `@UI.FieldGroup` annotation on the target entity, the correct `metaPath` format including the FieldGroup qualifier, FormElement paths relative to the navigation target only, and the dialog bound to the parent entity (not the navigation target). Any single mistake among these produces a blank dialog — often with no obvious error message.
 
 **CRITICAL PITFALL 2 — Two different event handler prefixes for two different contexts**:
 - **In a FE-managed column template fragment** (the Link cell in the table): use the full extension path `.extension.<namespace>.<ControllerName>.<methodName>`. Example: `press=".extension.my.app.ext.controller.ListReportExt.onLinkPress"`. This works because FE's XML template processor resolves this against the List Report view's controller.
@@ -33,6 +33,14 @@ Replace all placeholder names with your actual values:
 
 **CRITICAL PITFALL 8 — Provide a unique suffix in the `Fragment.load` `id` parameter**: The `id` passed to `Fragment.load()` is used to prefix all control IDs inside the fragment. Using just `oView.getId()` (no suffix) means all controls get the same prefix as the view itself — this causes ID conflicts when a second fragment is loaded in the same view. Always use a unique, descriptive suffix: `id: oView.getId() + "--relatedEntityPopup"`. This guarantees uniqueness and prevents duplicate-ID errors if the component is reused.
 
+**CRITICAL PITFALL 9 — `macros:Form` crashes with `Cannot create form based on ReferenceURLFacet` when the target entity has a media/stream facet**: When `macros:Form metaPath` points to a navigation property without a FieldGroup qualifier (e.g. `metaPath="_Agency"`), the building block reads `@UI.Facets` for that entity to auto-generate form containers. If any facet is of type `UI.ReferenceURLFacet` (common on entities exposing stream/attachment/media properties), the form throws `Cannot create form based on ReferenceURLFacet` and renders nothing. **Fix**: Add a `@UI.FieldGroup` annotation for the target entity in your local `annotation.xml`, then set `macros:Form metaPath` to explicitly target that FieldGroup: `"_Navigation/@com.sap.vocabularies.UI.v1.FieldGroup#Qualifier"`. This bypasses `@UI.Facets` processing entirely.
+
+**CRITICAL PITFALL 10 — `macros:Form metaPath` must target a FieldGroup with the full annotation path and no leading slash**: The correct format is `metaPath="_NavigationProperty/@com.sap.vocabularies.UI.v1.FieldGroup#Qualifier"`. Common wrong variants: (a) `metaPath="_Agency"` — triggers `@UI.Facets` auto-generation, may hit Pitfall 9; (b) `metaPath="/_Agency/@..."` — leading slash causes path resolution failure; (c) using the short alias in the attribute value (e.g. `@UI.FieldGroup#...`) — only valid inside annotation XML, not in XML fragment attribute values; always use the full namespace `com.sap.vocabularies.UI.v1.FieldGroup` in `metaPath` attribute values.
+
+**CRITICAL PITFALL 11 — `macros:FormElement metaPath` must be a bare property name relative to the navigation target, with NO navigation prefix**: `macros:Form`'s `metaPath` already navigates into the target entity. The child `macros:FormElement` `metaPath` values must therefore be **property names only** (e.g. `metaPath="Name"`), not `metaPath="_Agency/Name"`. Using the navigation prefix creates a double-navigation OData path (e.g. `/_Agency/_Agency/Name`) and causes the error `_Agency/_Agency/Name does not point to a property`. Strip all navigation prefixes from FormElement `metaPath` values — they are resolved relative to the Form's navigation target.
+
+**CRITICAL PITFALL 12 — Bind the dialog to the PARENT entity path, NOT to the navigation target, when using `macros:Form` with a navigation `metaPath`**: When `macros:Form metaPath` is `"_Navigation/@...FieldGroup#..."`, the dialog's `bindElement` must use the parent entity path (e.g. `Travel(...)`), **not** the navigation target path (e.g. `Travel(...)/_Navigation`). The building block navigates from the parent binding context through `_Navigation` automatically. If you `bindElement` to `Travel(...)/_Navigation` AND use `metaPath="_Navigation/..."`, the actual OData path becomes `/_Navigation/_Navigation/...` which does not exist. Correct usage: `oDialog.bindElement({ path: oBindingContext.getPath() })` where `oBindingContext` is the row's parent entity context.
+
 ---
 
 **STEP 1**: Register the custom column in manifest.json
@@ -276,17 +284,17 @@ field2Label=Field 2
 
 --------------------------------
 
-**TITLE**: ⚠️ DO NOT USE — Custom Column with Popup using macros:Form / macros:FormElement Building Blocks (BROKEN PATTERN)
+**TITLE**: Custom Column Link → Read-Only Popup Displaying OData Navigation Entity (macros:Form + macros:FormElement Building Blocks, OData V4) ✅ VERIFIED WORKING PATTERN
 
-**INTRODUCTION**: ⚠️ THIS PATTERN DOES NOT WORK. `sap.fe.macros.Form` and `sap.fe.macros.FormElement` building blocks do NOT render inside a `sap.m.Dialog` loaded via `Fragment.load()`. They require FE page infrastructure (template preprocessing, `__EntityControl` context) that is unavailable in manually loaded fragment dialogs. Using them results in a dialog that opens but shows no content — no fields are rendered and no error is thrown. Additionally, the close button handler in this pattern wrongly uses `.extension.XXX.onCloseAgencyPopup` — this silently fails for Fragment.load dialogs (the button click does nothing). Use the SimpleForm pattern documented in the first section above instead.
+**INTRODUCTION**: This is an alternative to the SimpleForm pattern above. Use this pattern when you specifically need `sap.fe.macros.Form` and `sap.fe.macros.FormElement` building blocks in the popup (e.g. to leverage FE field rendering, built-in labels from OData annotations, or value help display). This pattern requires additional setup compared to SimpleForm — specifically a `@UI.FieldGroup` annotation in `annotation.xml` — but renders fields using the same FE building blocks used in Object Pages.
 
-**TAGS**: custom column, popup, dialog, Form building block, FormElement building block, sap.fe.macros.Form, sap.fe.macros.FormElement, controller extension, list report, extension, fragment, building blocks, data visualization, association, XML fragment, BROKEN, DO NOT USE
+Key differences from the SimpleForm pattern:
+1. Must add `@UI.FieldGroup` annotation for the navigation target entity in `annotation.xml` (to avoid `ReferenceURLFacet` crash — see Pitfall 9)
+2. `macros:Form metaPath` must target the FieldGroup explicitly: `"_Navigation/@com.sap.vocabularies.UI.v1.FieldGroup#Qualifier"` (see Pitfall 10)
+3. `macros:FormElement metaPath` values are property names only — no navigation prefix (see Pitfall 11)
+4. Dialog must be bound to the PARENT entity path, not the navigation target (see Pitfall 12)
 
-**STEP**: Register the custom column in manifest.json
-
-**DESCRIPTION**: ⚠️ DO NOT USE THIS PATTERN. See the SimpleForm pattern above.
-
-**LANGUAGE**: JSON
+The column template fragment, manifest.json column registration, controller extension structure, and i18n keys follow the same rules as the SimpleForm pattern (
 
 **CODE**:
 ```JSON