Skip to content

docs(integrations): clarify entry accepts any fragment key + FAST-v3 wrapper requirement#308

Open
janechu wants to merge 1 commit into
mainfrom
users/janechu/clarify-embedded-entry-in-integration-docs
Open

docs(integrations): clarify entry accepts any fragment key + FAST-v3 wrapper requirement#308
janechu wants to merge 1 commit into
mainfrom
users/janechu/clarify-embedded-entry-in-integration-docs

Conversation

@janechu
Copy link
Copy Markdown
Contributor

@janechu janechu commented May 19, 2026

What

Two small clarifications carried forward from the discussion on #299 (which was closed in favour of inline updates rather than a separate recipe page, per maintainer preference):

  1. Both docs/guide/integrations/node.md and docs/guide/integrations/rust.md now explicitly state that entry / entry_id accepts any fragment key in the built protocol, not just "index.html". Adds a webui inspect pointer for listing the valid keys.

  2. Calls out the FAST-v3 wrapper-file requirement: an <f-template name="my-component"> block lives in the protocol's component map (not the fragment map), so it cannot be passed as entry directly. Adopters trying to render a single FAST-v3 component into an embedded host were hitting MissingFragment and had to read source to figure out why.

Also adds a one-line distinction between render_partial (returns JSON for the WebUI client-side router during in-app navigation) and render / WebUIHandler::handle with entry (returns raw HTML for any host), since these two APIs were being conflated in the discussion on #299 and the existing docs don't make the distinction explicit.

Why

The existing integration pages say entry is "Fragment ID to start rendering from" but only ever show entry: 'index.html' in examples. An adopter has to read the source to figure out (a) that they can pass any fragment, (b) how to list valid keys, and (c) why their FAST-v3 <f-template> block doesn't work as an entry. These three points together are ~20 lines of doc that pay back the source-reading exercise.

How I tested

  • cargo xtask license-headers
  • cargo fmt --all --check ✔ (docs-only change; ran for sanity)
  • No new markdown directives, no new code samples; all internal links resolve against existing files.

Notes

…wrapper requirement

Two small clarifications carried forward from the discussion on #299
(which was closed in favour of inline updates rather than a separate
recipe page):

1. Both Node and Rust integration pages now explicitly state that
   `entry` / `entry_id` accepts any fragment key, not just
   `"index.html"`. Adds a 'webui inspect' pointer for listing the
   valid keys in a built protocol.

2. Calls out the FAST-v3 wrapper-file requirement: an
   `<f-template name="...">` block lives in the protocol's
   component map (not the fragment map), so it cannot be passed as
   `entry` directly. Adopters trying to render a single FAST-v3
   component into an embedded host were hitting MissingFragment and
   had to read source to figure out why.

Also adds a one-line distinction between `render_partial` (returns
JSON for the WebUI client-side router during in-app navigation) and
`render` / `WebUIHandler::handle` with `entry` (returns raw HTML
for a non-WebUI host), since these two APIs were being conflated and
the existing docs don't make the distinction explicit.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant