Skip to main content

Module preview_url

Module preview_url 

Source
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:

PlaceholderValue
{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 None when 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.