Block preview page
The hidden block preview page of AntelopeJS DMS, which draws a tree of registered blocks from a URL or from postMessage, and powers the live previews of these docs.
/dms-preview is a public, hidden page of the DMS. It renders a tree of registered DMS blocks without the dashboard header or sidebar. The live previews of the component pages embed it in an iframe, and you can open it to try blocks without writing a page.
Turn the page on
The DMS serves the page when one of these conditions holds:
- The AntelopeJS runtime runs in development mode (
GetRuntimeInfo().dev). - The DMS module config sets
docsPreview: true. - The environment sets
DMS_DOCS_PREVIEW=1.
ajs project dev and ajs project run start the runtime in development mode, so the page is on there. For a build started with ajs project start, use one of these settings:
dms: {
config: {
docsPreview: true,
},
},
ajs project build
DMS_DOCS_PREVIEW=1 ajs project start
The page answers at <clientBaseUrl>/dms-preview, which is http://localhost:3001/dms-preview with the default clientBaseUrl. The @antelopejs/dms playground sets docsPreview: true.
docsPreview: false does not turn the page off in development mode or when DMS_DOCS_PREVIEW=1 is set. NODE_ENV does not decide the runtime's development mode. The DMS checks these conditions once, when it constructs the module, so restart the backend after you change one.
The page is public, so anyone who can reach the dashboard can open it. It draws only registered block types, and it lets them read only relative URLs of the same site. A block that reads a route still calls that route. Enable the page on a demo instance, not on a production dashboard that holds real data.
Render a tree from the URL
Pass the tree in ?state=, as base64url-encoded JSON of this shape:
interface PreviewState {
tree: PreviewNode | PreviewNode[];
theme?: "light" | "dark";
locale?: string;
padding?: boolean;
transparent?: boolean;
}
interface PreviewNode {
type?: string;
componentName?: string;
options?: Record<string, unknown>;
children?: Array<PreviewNode & { id?: string; slot?: string; colSpan?: number }>;
}
| Field | Meaning |
|---|---|
tree | One block, or a list of blocks drawn one after the other. |
theme | The color mode of the preview. |
locale | A locale the dashboard knows, such as fr-FR. |
padding | Pads the blocks off the edges of the frame. Defaults to true. |
transparent | Paints no background, so the embedding page shows through. |
type | A registered block type, such as KpiCard. It wins over componentName. |
componentName | The component a registered block type emits, such as dms-kpi-card. |
options | The block's options. |
children | The nested blocks, each with an optional id, slot and colSpan. |
const state = {
tree: { type: "KpiCard", options: { title: "Revenue", staticValue: 48200, staticDelta: 12.4, showDelta: true } },
theme: "dark",
};
const encoded = Buffer.from(JSON.stringify(state)).toString("base64url");
console.log(`http://localhost:3001/dms-preview?state=${encoded}`);
The block catalog decides what the page may draw. A node names a registered type, or a componentName that belongs to a registered type. The page draws an inline notice instead of the block in these cases:
- The node names no registered type.
- The block needs a backend class, such as a
TableViewor aResourceForm. - An option whose name ends in
Url, such asfetchUrlorsubmitUrl, or an option namedlocation, holds a value that is not a relative path of the same site. - An option whose name ends in
UrlMethodholds a method other thanGETorHEAD.
Drive it with postMessage
In an iframe, the page exchanges messages with its parent window. Every message carries channel: "dms-preview".
| Direction | Message | Meaning |
|---|---|---|
| iframe to parent | { channel, type: "ready" } | The page is mounted. Send render now. |
| parent to iframe | { channel, type: "render", tree, theme?, locale?, transparent? } | Draw this tree. A missing theme, locale or transparent keeps its previous value. |
| parent to iframe | { channel, type: "theme", theme } | Switch between light and dark. |
| parent to iframe | { channel, type: "min-height", height } | The frame, with its sidebar, is at least this tall in CSS pixels, so a short page fills the window it is drawn in. 0 lifts the floor. |
| iframe to parent | { channel, type: "resize", height } | The content is now this tall, in CSS pixels. |
| iframe to parent | { channel, type: "error", message } | Something could not be drawn. |
const frame = document.querySelector("#preview");
if (!(frame instanceof HTMLIFrameElement)) throw new Error("#preview is not an iframe");
const CHANNEL = "dms-preview";
window.addEventListener("message", (event) => {
const target = frame.contentWindow;
if (!target || event.source !== target || event.data?.channel !== CHANNEL) return;
if (event.data.type === "ready") {
target.postMessage(
{ channel: CHANNEL, type: "render", tree: { type: "Banner", options: { tone: "info", title: "Hello" } } },
"*",
);
}
if (event.data.type === "resize") frame.style.height = `${event.data.height}px`;
});
By default the page paints the dashboard's own background. On an embedding page of another color, that background shows as a lighter or darker rectangle. Set transparent: true, in ?state= or in a render message, to paint no background, so the blocks sit on the embedding page's background. A transparent preview declares the color scheme of its theme. A browser keeps an iframe opaque when that scheme differs from the embedding page's, so send the theme that matches the page's mode, such as dark on a page with color-scheme: dark.
Draw blocks in your own components
The page renders the tree with DmsBlockPreview, a component of the DMS frontend. Pass it a tree to draw blocks inside any custom component. The mockup viewer uses it the same way.
<template>
<DmsBlockPreview :tree="{ type: 'EmptyState', options: { title: 'No invoices yet' } }" padding />
</template>
Outside /dms-preview, the component fetches the list of block types it may draw from GET /api/block-preview/types. That route requires a signed-in member of the workspace.