[data-reveal]{opacity:1!important;transform:none!important}
AntelopeJS DMS
DocumentationBlock preview page

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:

antelope.config.ts ts
dms: {
  config: {
    docsPreview: true,
  },
},

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.

Warning

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:

ts
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 }>;
}
FieldMeaning
treeOne block, or a list of blocks drawn one after the other.
themeThe color mode of the preview.
localeA locale the dashboard knows, such as fr-FR.
paddingPads the blocks off the edges of the frame. Defaults to true.
transparentPaints no background, so the embedding page shows through.
typeA registered block type, such as KpiCard. It wins over componentName.
componentNameThe component a registered block type emits, such as dms-kpi-card.
optionsThe block's options.
childrenThe nested blocks, each with an optional id, slot and colSpan.
scripts/preview-url.ts ts
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 TableView or a ResourceForm.
  • An option whose name ends in Url, such as fetchUrl or submitUrl, or an option named location, holds a value that is not a relative path of the same site.
  • An option whose name ends in UrlMethod holds a method other than GET or HEAD.

Drive it with postMessage

In an iframe, the page exchanges messages with its parent window. Every message carries channel: "dms-preview".

DirectionMessageMeaning
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.
docs/preview-embed.ts ts
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.

app/components/BlockIdea.vue vue
<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.

Next steps

Components

The blocks you can preview.

Configuration

Every key of the DMS module config.