docs: update critical pitfalls for mock data and bindElement usage in Fiori extension instructions

Author: devinea

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

@@ -29,7 +29,7 @@ Replace all placeholder names with your actual values:
 
 **CRITICAL PITFALL 6 — Use `this.base.getView()` in a ControllerExtension, not `this.getView()`**: Inside a `sap.ui.core.mvc.ControllerExtension`, `this.getView()` does not exist. Use `this.base.getView()` to get the view instance. This is required for `oView.getId()`, `oView.addDependent()`, etc.
 
-**CRITICAL PITFALL 7 — Create mock data JSON for the navigation target entity set**: When running with a mock server (e.g. `ui5-mock.yaml`), the mock server serves entity sets from JSON files in `localService/mainService/data/`. If the navigation target entity set (e.g. `RelatedEntitySet`) has no corresponding JSON file, the dialog opens but shows empty fields — no error. Check the `EntityContainer` in `metadata.xml` for the correct entity set name, then create the JSON file. Do NOT include stream/media properties (e.g. `Attachment` of type `Edm.Stream`) — they cause mock server errors.
+**CRITICAL PITFALL 7 — Create mock data JSON for the navigation target entity set**: When running with a mock server (e.g. `ui5-mock.yaml`), the mock server serves entity sets from JSON files in `localService/mainService/data/`. If the navigation target entity set (e.g. `RelatedEntitySet`) has no corresponding JSON file, the dialog opens but shows empty fields — no error. The mock server determines which JSON file to use for a navigation property by looking at the `NavigationPropertyBinding` `Target` attribute on the parent EntitySet in `metadata.xml`. For example, if `metadata.xml` has `<NavigationPropertyBinding Path="_Agency" Target="TravelAgency" />` on the Travel EntitySet, the mock server will look for `data/TravelAgency.json` when the `_Agency` navigation property is requested. The filename must exactly match the `Target` value (case-sensitive). Check the `EntityContainer` in `metadata.xml` for all `NavigationPropertyBinding` entries on your parent entity set to find the correct target name. Do NOT include stream/media properties (e.g. `Attachment` of type `Edm.Stream`) — they cause mock server errors.
 
 **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.
 
@@ -41,7 +41,9 @@ Replace all placeholder names with your actual values:
 
 **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.
 
-**CRITICAL PITFALL 13 — `bindElement` must use a plain absolute path string — do NOT pass an OData context object inside its parameters**: In OData V4, bind a dialog to a navigation entity using `oDialog.bindElement(oContext.getPath() + "/_NavigationProperty")` — a plain string argument. Do NOT use a form like `oDialog.bindElement({ path: "_Navigation", parameters: { context: oBindingContext } })`. OData V4 binding context objects contain circular references (bidirectional parent↔child context chains) that cause the framework to throw `"Converting circular structure to JSON"` when it attempts to serialize the binding parameters. The absolute-path string form avoids serialization entirely and is always correct for navigating to an associated entity. When you need to pass additional OData binding parameters (e.g. `$$ownRequest`), use only serializable values — never pass a context object.
+**CRITICAL PITFALL 13 — `bindElement` — do NOT pass an OData context object inside `parameters`**: In OData V4, both `oDialog.bindElement(absolutePathString)` and `oDialog.bindElement({ path: absolutePathString })` work correctly. The **object form** `{ path: "..." }` is preferred for OData V4 because it allows adding binding parameters when needed (e.g. `{ path: "...", parameters: { $$ownRequest: true } }`). The working Step 5 code uses this object form. The critical warning is: do NOT pass an OData context object as a value inside `parameters`, i.e. do NOT write `oDialog.bindElement({ path: "_Navigation", parameters: { context: oBindingContext } })`. OData V4 context objects contain circular references (bidirectional parent↔child context chains) that cause the framework to throw `"Converting circular structure to JSON"` when it serializes the binding parameters. Use only the absolute path string derived from `oContext.getPath()` — never pass the context object itself.
+
+**CRITICAL PITFALL 14 — Must `return oDialog` from the `.then()` callback inside `Fragment.load().then()`**: When storing a Fragment.load Promise as `this._pRelatedEntityDialog`, the `.then()` callback where `oView.addDependent(oDialog)` is called MUST end with `return oDialog`. If omitted, the Promise resolves to `undefined` (the implicit return value). All subsequent calls like `this._pRelatedEntityDialog.then(function(oDialog) { oDialog.open(); })` will then receive `undefined` as `oDialog` — `oDialog.open()` silently fails or throws `TypeError: Cannot read properties of undefined`. This is the single most common silent failure in the Fragment.load Promise pattern. Always write: `.then(function(oDialog) { oView.addDependent(oDialog); return oDialog; })`. As a related convention: prefix all Promise-stored dialog references with `_p` (e.g. `_pRelatedEntityDialog`, `_pAgencyPopup`) to visually distinguish them from direct object references — this makes it immediately clear that `.then()` must be used to access the dialog.
 
 ---