DMS Builder Documentation · Interface reference

If you want to edit a page with the mouse instead, start with the visual builder guide.

Quick Start

This example creates a Revenue page with a Total revenue card. Run it once from a backend module after the builder is available, in a development project that loads both @antelopejs/dms and @antelopejs/dms-builder. Installing the interface package alone does not provide the implementation.

The project must already have a pages category. Use ListCategories() to find yours, or create a category first. Choose an unused page name: running a creation twice returns duplicate_name.

import {
  AddBlock,
  CreatePage,
} from "@antelopejs/interface-dms-builder";

const page = await CreatePage({
  name: "revenue",
  displayName: "Revenue",
  category: "pages",
  icon: "i-ph-chart-line",
});
if (!page.ok) {
  throw new Error(`could not create the page: ${page.error.code}`);
}

const block = await AddBlock({
  page: page.data.ref, // "/revenue"
  name: "total",
  type: "KpiCard",
  config: {
    title: "Total revenue",
    icon: "i-ph-currency-eur",
  },
});
if (!block.ok) {
  throw new Error(`could not add the block: ${block.error.code}`);
}

console.log(block.data.path); // "/revenue#total"
for (const change of block.changes) {
  console.log(change.kind, change.path);
}

After the backend reloads, open /revenue as a tenant owner. You should see the page and its card; the card has no revenue data yet. Queries connects a card to a resource when you are ready for real numbers.

Each call saves independently. If CreatePage succeeds but AddBlock fails, the empty page remains; fix the block configuration and retry that call, not the page creation.

How an edit reaches your files

A block is one DMS component, such as a card or a table. Adding one writes a factory call into a PageController class, either as a static field or as a child of another block. The builder parses the source, stages the edit in memory and typechecks the project before writing it. A type error anywhere in the project can therefore block the edit.

Operations are InterfaceFunction exports from @antelopejs/interface-core. Expected failures return values you can inspect:

// Success: { ok: true, data, changes, warnings? }
// Failure: { ok: false, error }

Listing operations such as ListPages return their value directly. See Results and errors for the full contract. When you read before writing, pass the structure's version as expectedVersion so another editor's work is not overwritten.

Hand-written declarations remain editable when the builder recognizes their shape. Otherwise, it marks them opaque: you can inspect them without asking the builder to rewrite code it does not understand. Use Drafts and preview when an editor needs to save a whole block tree in one transaction.

Documentation Sections

Addressing and Structure - The refs that name a page, a block and a category, and the shapes the builder reads back
Catalog - The block types, DataTypes and reserved names the builder can report
Page Operations - Create pages and categories, and edit a page's block tree
Resources - Generate tables, DataAPI controllers and their fields
Queries - Compile a measure, grouped or not, into a model method and a page route
Value Encodings - Write configuration values that are not plain literals
Results and Errors - Branch on OpResult, read diagnostics, and make a write conditional
Drafts and Preview - Write a page's blocks and the data they read in one transaction, and preview either
A Chart Without Code - The whole journey, from picking a measure to reopening the page