Embedded pages: overview

{}

BESPA gives you three ways to render one page inside another. They share the same mechanism — EmbedHandler invokes a handler against an in-memory response recorder, slices the resulting <body>, and drops it into a container widget. What differs is the container and the state contract around it.

Use this page to pick the right one. Each row links to its deep-dive.

At a glance

Mechanism	Container	Controlled by	Visually	Reach for it when
Inline embed	`GroupingFrame`, any container	A boolean-ish state key (`HideIfEmpty`)	Part of document flow	A sub-page belongs in-line — a detail strip, a settings block under a header
Modal	`Modal("key")`	One state key holding the embedded path	Centered overlay, dims background	A focused interaction that should pause the rest of the page
Side panel	`SidePanel("key")`	One state key holding the embedded path	Sliding pane, doesn’t dim	A contextual surface the user reads beside the main content
Named frame	`GroupingFrame(...).WithName("x")`	Links that set `WithTarget("x")`	Multiple independent surfaces on one screen	A dashboard, IDE-style split, or chat-and-thread layout — each pane navigates on its own

How they relate

All four are the same shape under the hood:

container.Add(wf.EmbedHandler(handler, r, "GET", path, nil))

What changes is the container widget and how path is decided:

Inline embed — path is fixed in code (or computed once). The container shows or hides based on a state predicate.
Modal / Side panel — path is read from a state variable. Empty state means the overlay isn’t rendered. Setting the state to a path opens it; clearing the state closes it.
Named frame — path is fixed at first paint, but the frame is given a name via WithName. Subsequent links elsewhere on the page can swap the frame’s content by targeting that name.

State isolation is the same everywhere

Whichever mechanism you pick, the embedded page sees an isolated slice of state. A variable named x in the embed doesn’t collide with one of the same name in the parent. That’s what lets you compose pages without coordinating their state vocabularies.

Which one am I looking at?

A useful disambiguation when you’re reading example code:

See wf.Modal("...") or wf.SidePanel("...") at the top of the page → overlay. State key in the constructor.
See wf.GroupingFrame(...).WithName("...") → named frame. Look for links with WithTarget("...") matching that name.
See wf.GroupingFrame(...) without WithName, holding an EmbedHandler → inline embed. Usually paired with HideIfEmpty or a similar predicate.

Common traps

Two modals stacked. Allowed, almost never right — usually a sign one of the steps should be a full page. The convention is at most one level of modal nesting.
Overlay state and frame target collision. Don’t reuse the same name for a Modal state key and a frame name. They live in different namespaces but a reader of your code won’t know that.
Forgetting _back. Overlays install ?_back=^?modal= (or similar) so the embedded page can dismiss itself. Inline embeds and named frames usually don’t — the dismiss model is different.
Expecting a named frame to survive a top-level reload. Frame contents are part of the page render. A full reload starts the frame at its initial content.

Deep dives

Nesting pages — the four containers side by side in one demo (modal, side panel, inline, full page), with the _back plumbing explained.
Targeting frames — named frames and the _top / _parent / _blank / custom-name target keywords.
Build → Modals & side panels — the consumer-side recipes: opening, closing, returning data, dirty-state confirmation.
The action-URL pattern — the ^ and ~ prefixes that overlays and frames lean on.