Drafts and preview
SetPageBlocks writes a page's whole block tree and its queries in one transaction, PreviewLayout serializes a draft without writing it, and PreviewQuery runs an unsaved query against the real table.
PreviewLayout serializes a page draft without writing files. SetPageBlocks saves the draft's complete block tree in one transaction. A successful preview does not mean that the draft compiles, because only the write runs the typecheck.
Warning:
SetPageBlocksreplaces the whole block tree. Blocks you omit are removed. For one small change to an existing page, useConfigureBlockinstead.
Preview one card
With an existing /dashboard page, this read-only example returns a serialized KPI card. An editor can render preview.data.components.total. No source file changes.
import { PreviewLayout } from "@antelopejs/interface-dms-builder";
const preview = await PreviewLayout("/dashboard", {
blocks: [{ name: "total", type: "KpiCard", config: { title: "Total revenue" } }],
});
if (preview.ok) {
console.log(preview.data.components.total);
console.log(preview.data.degraded);
} else {
console.error(preview.error);
}
Each per-block operation saves at once. A visual editor usually holds its edits locally and calls SetPageBlocks once. The block tree and its queries then pass one typecheck together, or the page stays unchanged.
Describe a draft
PageDraft is a page as you want it written.
| Field | Type | Description |
|---|---|---|
page | Partial<EditablePageMeta> | Metadata to patch alongside the blocks. Omit it to leave the metadata alone. |
blocks | BlockDraft[] | The top-level blocks, in page order. |
queries | AddQueryInput[] | The queries the page serves, written with the blocks. Omit it to leave the page's queries alone. |
A block and the data it reads are one edit, so they are one write. The blocks, the model methods and the routes land in a single transaction with a single typecheck, or none of them land.
An omitted queries and an empty array differ. An omitted queries leaves the queries the page already serves untouched. An empty array says that the page serves none, and removes the generated ones. Two queries in a draft with the same name fail with invalid_config.
A draft never removes or rewrites these two kinds of query:
- A query edited past the grammar. The write leaves it exactly as it is, whether the draft still lists it or not, and reports a
query_opaquewarning. The builder cannot read the chain, so a person owns it. - A query the draft left out while a block still reads it. The write keeps the query when a block on the page still names its URL, and reports a
query_keptwarning. Removing the query would break that block.
import { SetPageBlocks } from "@antelopejs/interface-dms-builder";
await SetPageBlocks("/shop/board", {
blocks: [
{
name: "revenueChart",
type: "ChartCard",
config: {
title: "Revenue",
fetchUrl: "/dms/pages/shop/board/stats/revenue",
chart: { $block: { type: "ChartArea", config: { xaxisType: "category" } } },
},
},
],
queries: [
{
name: "revenue",
resource: "order",
template: "series",
params: { op: "sum", field: "amount", groupBy: "createdAt", bucket: "month" },
response: "card",
},
],
});
BlockDraft is one block:
| Field | Type | Description |
|---|---|---|
name | string | The static key (top level) or the .child() id (nested). Must be a valid identifier. |
type | string | A BlockTypeDescriptor.type from the catalog. Required unless preserve is set. On a preserved block, a type that differs from the one on disk is refused. |
config | ConfigObject | The factory's options. Leave out locked options, because the server keeps their source. A preserved block takes no config. |
lockedOptions | Record<string, string> | Read-only UI hints copied from GetPageStructure. The server derives option locks from its own source. |
slot | string | The slot the block sits in. |
meta | ConfigObject | Child metadata emitted with slot, such as { colSpan: 2 } on a grid child. |
controller | ResourceRef | Required for a controller-leading type such as TableView. |
children | BlockDraft[] | Nested blocks, in .child() order. |
preserve | boolean | Write the block back exactly as it stands on disk. |
Carry an opaque block through a write
A whole-tree write has to keep the blocks that the builder can read but not rewrite. These include a CustomComponent, a block behind a computed expression, and any block that GetPageStructure reported with editable: false. Set preserve on such a block. The write matches the block by name among its siblings and writes its source text back untouched. A locked block without preserve is refused.
To change only the page title, preserve every top-level block. A preserved block keeps its children, so you do not rebuild editable blocks from part of their configuration:
import {
GetPageStructure,
SetPageBlocks,
} from "@antelopejs/interface-dms-builder";
const structure = await GetPageStructure("/dashboard");
if (structure.ok) {
const blocks = structure.data.blocks.map((block) => ({
name: block.name,
preserve: true,
}));
const result = await SetPageBlocks("/dashboard", {
page: { displayName: "Revenue" },
blocks,
}, {
expectedVersion: structure.data.version,
});
if (!result.ok) console.error(result.error);
}
When you edit a block, supply its full draft, including its children, slot, meta and controller where they apply. Do not reduce a block tree to names and configuration objects, because the write deletes omitted children.
The children of a preserved block are read-only. If a preserved block lists children, each child must also be preserved, with the names, slots and metadata it has on disk. A block with locked options keeps its type, its controller and the placement of its children, and the draft cannot copy it to another path.
A preserve block whose name matches nothing on disk is rejected with invalid_config.
Write a whole page
import { GetPageStructure, SetPageBlocks } from "@antelopejs/interface-dms-builder";
const structure = await GetPageStructure("/dashboard");
if (!structure.ok) throw new Error(structure.error.code);
const result = await SetPageBlocks(
"/dashboard",
{
page: { displayName: "Revenue" },
blocks: [
{
name: "kpis",
type: "Grid",
config: { gap: "1rem" },
children: [
{
name: "row",
type: "GridRow",
children: [
{
name: "revenue",
type: "KpiCard",
config: { title: "Revenue", valueFormat: "currency" },
meta: { colSpan: 2 },
},
],
},
],
},
],
},
{ expectedVersion: structure.data.version },
);
if (!result.ok) throw new Error(result.error.code);
Read the version immediately before you prepare the draft. If the write returns stale, read the page again and review the other editor's changes before you retry.
On success, the result carries the staged changes and the page's new version. Pass that version as the next expectedVersion.
The write removes the blocks that the draft leaves out. It leaves static members that are not blocks where they are. It drops a named import that the file used before the write and no longer uses. An import that was already unused before the write stays.
$expr is refused anywhere in a draft, including page and a block's meta. A whole-tree write stays structured, and arbitrary code would break that guarantee. $dataType, $ref and $block are accepted. See Value encodings.
Read the failures
SetPageBlocks validates the whole draft before it touches anything. One call reports every problem at once as an invalid_config issue, each addressed by a JSON pointer into the draft:
| Pointer | Cause |
|---|---|
/blocks/1/name | Not a valid identifier, or a duplicate among its siblings. |
/blocks/2/type | An unknown block type. |
/blocks/2/children | Children on a block type that takes none. |
/blocks/2/children/0/type | A child type that the container does not accept. |
/blocks/0/controller | A controller-leading type without a controller, or a controller on a type that takes none. |
/blocks/3/config/title | $expr inside a config value. |
/blocks/4 | A preserve block with no match on disk, a locked block without preserve, or a change to a preserved block. |
Beyond invalid_config, the write fails the same way as the per-block operations. It returns stale when expectedVersion no longer matches, and typecheck_failed when the emitted source does not compile. In both cases nothing is written. See Results and errors.
Preview a draft
PreviewLayout serializes a draft the way the runtime would, through the block factories of @antelopejs/interface-dms/base that the emitted source calls. It runs no typecheck and writes nothing to disk, so an editor can run it on every edit.
const preview = await PreviewLayout("/dashboard", draft);
if (preview.ok) {
const grid = preview.data.components.kpis; // ComponentPreview
}
PageLayoutPreview holds:
| Field | Type | Description |
|---|---|---|
components | Record<string, ComponentPreview> | The serialized tree, keyed by top-level block name. The DMS frontend renders this shape. |
degraded | BlockPath[] | Blocks that the preview could not build faithfully. |
A degraded block appears in components as a placeholder that names the reason. A block lands in degraded in these cases:
- It is a
preserveblock, or a block with locked options, which the draft does not describe. - Its type is unknown.
- It is a controller-leading block, such as
TableView, with nocontroller, or with a resource whose DataAPI class the running app has not loaded. A table created a moment ago is not loaded until the app reloads. - Its config holds an
$expr, or a$refto a resource whose DataAPI class the running app has not loaded. - Its factory threw.
For a degraded block, render the last known-good layout rather than trust the preview.
Preview a query
PreviewLayout shows what the page looks like. PreviewQuery shows the data its blocks display. It runs a query that is not saved and answers what its route would, so an editor can configure a source against real data before anything is written.
import { PreviewQuery } from "@antelopejs/interface-dms-builder";
const result = await PreviewQuery({
query: {
name: "revenue",
resource: "order",
template: "series",
params: {
op: "sum", field: "amount", groupBy: "createdAt", bucket: "month",
where: [
{ field: "createdAt", op: "ge", value: { $param: { name: "from" } } },
{ field: "createdAt", op: "lt", value: { $param: { name: "to" } } },
],
},
},
args: { from: "2026-01-01T00:00:00.000Z", to: "2026-09-01T00:00:00.000Z" },
});
if (result.ok) {
console.log(result.data.body); // { series: [{ x: 202601, y: 1250 }, …] }
console.log(result.data.truncated); // whether it stopped reading early
}
| Field | Type | Description |
|---|---|---|
query | AddQueryInput | The query to run. The template validates its parameters as it does for AddQuery. |
args | ConfigObject | The values the route would receive, under the names the route exposes. |
tenant | string | Whose rows to read, for a resource in a per-tenant schema. A resource in any other schema ignores it. |
QueryPreview holds the route's own response body and how it is arranged:
| Field | Type | Description |
|---|---|---|
output | QueryOutputKind | "scalar" or "series", as GetPageStructure reports the saved query. |
response | QueryArrangement | Set only when a DMS helper arranged the body, the same condition under which read-back reports it. |
body | QueryResponseBody | What the route would return. |
truncated | boolean | true when the preview stopped at 500 points. |
The body depends on the calculation and on response:
- A scalar calculation answers
{ value }, whateverresponseasks for. - A grouped calculation with no
response, or withresponse: "series", answers{ series }and leavesresponseunset. response: "card","value"and"items"answer the body thatchartCardData,kpiCardDataandtopListDatafrom@antelopejs/interface-dms/base/query-responsebuild. The generated route calls the same helper, so"card"answers aChartCardData, headline figure included, and a block can take it directly.
A query is filters, a grouping and a measure. It has no way to express a write, so a preview only reads. It stops at 500 points and sets truncated, so a chart that lost its tail says so.
PreviewQuery answers every failure as a failed OpResult, never as a rejected promise:
not_foundfor an unknown resource.invalid_configfor an unknown template or invalid parameters.unsupportedwhen the resource's schema is not registered, when a bound value has no argument inargs, or when the database refuses the query.
Next steps
- A chart without code follows these calls from the choice of a measure to the reopened page.
- Results and errors shows how to branch on
OpResultand handlestale. - Catalog lists the block types, their schemas and their defaults.