A BESPA page is a self-contained unit: its own AppBar, its own state, its own redraw boundary. The framework lets you embed one page inside another so you can compose larger UIs out of those units. The nested page doesn’t know — or care — whether it’s the top of the document or sitting inside a modal frame somewhere.
The same nested page can appear in any of these containers. Pick a button to embed /basics/nested using that modality — and notice how the embedded page keeps its own counter state independent of this outer page:
This page has no knowledge of what container it is nested inside — if any. Its state, navigation, and redraws are entirely self-contained.
A back arrow shows in the AppBar so the user can return to the container. Additional close controls — link, button — can also use WithHrefBack:
Each container widget — Modal, SidePanel, or a plain GroupingFrame — embeds the nested handler with EmbedHandler. The handler is invoked against an in-memory response recorder, the resulting HTML is sliced out of its <body> tag, and dropped into the container. The nested page renders exactly the same widgets it would render on its own URL.
Two things make the nesting clean:
x in the embedded page doesn’t collide with one of the same name in the outer page. Click the embedded “Increment” link a few times in different modalities and watch each counter run independently.?_back=^?modal= parameter passed to EmbedHandler tells the nested page how to dismiss itself: when its back button runs RedirectBack, the response sends a ^?modal= redirect — “go up one page, clear modal” — which makes the outer page redraw the modal away.Modal — for a focused interaction that should pause whatever the user was doing. Centered, dimmed background, dismiss-via-cancel.SidePanel — for an inspector or contextual surface that sits beside the main content. Doesn’t dim the page; the user can still see and reference what’s underneath.GroupingFrame (or any container) — for inline composition. The embedded page is part of the document flow.Embedded pages: overview — the three embedding mechanisms compared in one table.
Targeting frames — how to direct a click at a specific named embedded frame rather than the current page.
The action-URL pattern — the ^ prefix used in the return-link plumbing.
Build → Modals & side panels — the consumer-side recipes for the most common embeds.