When a page has more than one embedded sub-page, you need a way to say which one a click should land in. BESPA borrows the idea — and the syntax — from classic HTML frames: each embedded page can be named, and a link or form can specify a target naming where its response should go.

Two named frames

The two grouping frames below contain embeds named one and two. The links above them target one or the other by name — the clicked path renders into the matching frame, leaving the rest of the page untouched:

Load page A into frame oneLoad page B into frame two

Click into frame one first. The loaded page contains its own link that targets frame two — cross-frame navigation from inside a frame. The page in frame two has a link targeting _top that replaces this whole document — escaping the frame structure entirely.

Target keywords

Three special target names are reserved, plus any custom name you assign with EmbedHandler(...).WithName("…"):

• _top — replace the outermost page in the browser tab. The reader leaves the current frame structure and lands in a fresh top-level document.
• _parent — replace the immediate parent page in the embedding hierarchy. Acts on the page that contains me.
• _blank — open in a new browser tab. The current document is unaffected.
• Any custom name (e.g. "one", "two") — finds the embed widget with the matching WithName anywhere in the page tree and renders into it.

Default targets

A page can declare a default target for all its links and forms via Page.WithTarget(name). This is what makes the action-URL pattern’s ^ prefix interesting: an embedded page that uses ^ walks up to its parent, picks up the parent’s default target, and lands the response there. Without a default target on the parent, ^/some/path behaves the same as /some/path.

When to use frames

Frames shine when a single screen has multiple independent surfaces that update on their own schedule — a chat thread next to a contact list, a code editor next to a preview pane, an inspector beside a main canvas. Each surface is its own BESPA page, with its own state and its own redraw boundary, and the user can navigate inside one without disturbing the others.

For single-purpose embeds (one modal at a time, one inline editor), see Nesting pages — usually simpler.

See also

Embedded pages: overview — the three embedding mechanisms side by side, with a table for picking the right one.

Nesting pages — the unnamed-embed case, for when there’s only one sub-page.

The action-URL pattern — the ^ / ~ prefixes that interact with frame targets.