Expand description
Preview a draft in a decoupled renderer.
preview_token mints a signed token and /api/v2/pages/{id}/ accepts
it, so the machinery for reading a draft over the API already worked.
What was missing was the hand-off: the mint endpoint lives inside the
session-gated admin, so the only way an editor could use it was to
copy a token out by hand. In practice that meant decoupled sites had
no preview at all.
This closes it. A tenant configures where its frontend lives, and the
page editor gains a link that carries a fresh token to it. The
frontend reads the token, calls the API with ?preview_token=, and
renders the draft with its own templates.
§The contract with the frontend
The configured value is a URL template. Each placeholder is substituted and percent-encoded:
| Placeholder | Value |
|---|---|
{token} | the signed preview token |
{path} | the page’s public URL path, e.g. /docs/intro — its / separators are kept, so the placeholder works in the path position (https://app.example.com{path}) as well as in a query value |
{id} | the page id |
https://app.example.com/api/preview?token={token}&path={path}A value with no placeholder is treated as a base URL and the
parameters are appended as a query string — so the simplest possible
configuration (https://app.example.com/preview) also works, and an
editor who pastes a bare URL is not left wondering why nothing
happens.
§When one page does not follow the pattern
Substituting {path} with the CMS’s url_path assumes the frontend
mirrors the CMS’s URL structure. Many do not — /features/ai-engine
here can be /product/ai-engine there, or /p/9, or a different app
altogether. Page::preview_path
overrides it per page, and for_page is where the two meet.
Constants§
- FIELD
- The field within that scope.
- SCOPE
- The site-settings scope holding the frontend’s preview entry point.
Functions§
- build
- Build the URL an editor should be sent to, or
Nonewhen the tenant has not configured a frontend. - configured_
base - Read the configured frontend URL for this tenant, if any.
- for_
page - Percent-encode a value for use in a query string.