Addressing and structure
The refs that name a page, a block and a category, and the page, block and listing shapes the builder reads back.
Overview
Every builder operation identifies its target with a string ref. This page covers PageRef for a page, BlockPath for a block inside it, and CategoryRef for a menu category. Resources and Queries define their own refs.
This page also describes the shapes the builder reads back. Those are the page metadata it can read and patch, the block tree it resolves from source, and the summaries the listing operations return. Page operations documents the operations that produce and take these shapes.
import type {
BlockPath,
CategoryRef,
PageRef,
} from "@antelopejs/interface-dms-builder";
const page: PageRef = "/dashboard";
const block: BlockPath = "/dashboard#kpis/row/revenue";
const category: CategoryRef = "pages.reports";
Address a page
PageRef is the route string of a page. The builder joins the slug of the category with the page's own urlSlug, which defaults to its name. A page named revenue under the root pages category is /revenue. CreatePage returns the ref it assigned, and every page operation takes it as its first argument.
import {
CreatePage,
GetPageStructure,
} from "@antelopejs/interface-dms-builder";
const created = await CreatePage({
name: "revenue",
displayName: "Revenue",
category: "pages",
});
if (created.ok) {
const structure = await GetPageStructure(created.data.ref); // "/revenue"
}
Address a block
BlockPath addresses one block inside a page. A top-level block is <pageRef>#<name>, and each nesting level below it adds /<childId>.
| Path | What it addresses |
|---|---|
/dashboard#kpis | The top-level block named kpis on /dashboard |
/dashboard#kpis/row | The .child("row", …) of that block |
/dashboard#kpis/row/revenue | The .child("revenue", …) of row |
The first segment after # is the static class member that declares the block. Every further segment is the id passed to .child(). AddBlock returns the path of the block it added.
Address a category
CategoryRef is the stable id of a category. The three roots are pages, modules and settings. The ref of a category under a parent joins the parent ref and the category id with a dot, so a reports category under pages is pages.reports. The root category of a module is modules.<moduleId>.
import { CreateCategory } from "@antelopejs/interface-dms-builder";
const category = await CreateCategory({
name: "reports",
displayName: "Reports",
parent: "pages",
});
// category.data.ref === "pages.reports"
Read a page's metadata
PageMeta holds what the builder knows about a page. It comes back inside the PageStructure that GetPageStructure returns.
| Field | Type | Description |
|---|---|---|
ref | PageRef | The page's route string. |
id | string | The page id, the first argument of its PageController. |
displayName | string | The label shown in the menu. |
icon | string | The icon name, when the page declares one. |
category | CategoryRef | The category the page belongs to. |
order | number | Sort order within the category. |
description | string | The page's description. |
hidden | boolean | Whether the page is hidden from the menu. |
permission | PagePermission | The permission guarding the page. |
live | PageLive | The Direct and Pause options of the page, when it is live. |
filepath | string | The file that declares the page. The builder's source index resolves it, not the runtime registry. |
hidden, permission and live read back like any other field when the page declares them as literals. A permission built from a call or a reference, such as an Action, reads back as undefined. The builder reports only what it can also rewrite.
PagePermission mirrors the DMS MenuOptions.permission. It is a partial permission spec with the fields id, title, icon, description, dependencies and defaultGranted. Its type is ConfigObject, an object of plain data, so the compiler refuses a function or a class instance. A bare action id is not accepted. The DMS types the option as Partial<Permission> | Action, so the builder would write a string and the typecheck gate would then refuse it.
import type { PagePermission } from "@antelopejs/interface-dms-builder";
const permission: PagePermission = {
id: "reports.export",
title: "Export reports",
};
The DMS also accepts an Action there. An Action is a live object and not data, so the builder has no encoding for it. A page that declares one reads its permission back as undefined.
PageLive mirrors the DMS MenuOptions.live, with the fields maxRate, slowRateAfter and rememberKey. It is a ConfigObject as well. When live is present, even as {}, the page is live. Its blocks then refetch through a Direct and Pause valve that its LiveToggle switches. When live is absent, the blocks refetch on every event. A patch that sends live as null removes it.
Patch a page's metadata
EditablePageMeta is the subset of PageMeta that ConfigurePage accepts as a patch. Its fields are displayName, icon, category, order, description, hidden, permission and live. ref, id and filepath are not patchable, because they follow from where the page lives.
A patch of category moves the page and changes its ref. The result carries the new ref, and a route_changed warning names the old route. Move a page between categories describes the move.
import type { EditablePageMeta } from "@antelopejs/interface-dms-builder";
const patch: Partial<EditablePageMeta> = {
displayName: "Monthly revenue",
order: 10,
};
Read the block tree
BlockNode is one block in the tree of a page. The builder resolves each static member and each .child() call it can parse. A block it cannot parse still appears as a node, marked not editable.
| Field | Type | Description |
|---|---|---|
path | BlockPath | The block's address. |
name | string | Static key for a top-level block, .child() id for a nested one. |
type | string | null | The factory name, or null when it does not resolve. |
editable | boolean | Whether the builder can edit the options it understands. false marks an opaque block. |
opaqueReason | string | Why the block is opaque. Set when editable === false. |
slot | string | The slot the block sits in, when its parent declares slots. |
meta | ConfigObject | Child metadata beyond slot, as declared in the third argument of .child(), such as { colSpan: 2 }. Nested blocks only. Keep it when you build a draft from the tree. |
config | ConfigObject | The options of the block that are literals. Present only when the block is editable. |
lockedOptions | Record<string, string> | The top-level options defined by an expression in code, each with the reason it is locked. A save keeps them unchanged. |
controller | ResourceRef | For a block whose factory takes a controller first, such as TableView, the resource that the leading argument resolves to, when it is a known generated resource. |
children | BlockNode[] | Container blocks only, in .child() order. |
The builder can read an opaque block but cannot rewrite it. A block behind an unresolved reference is opaque, and so is a block that a computed expression produces instead of a direct factory call. ConfigureBlock on it, AddBlock under it and MoveBlock onto it fail with opaque_target, which Results and errors describes.
import { GetPageStructure } from "@antelopejs/interface-dms-builder";
const result = await GetPageStructure("/dashboard");
if (result.ok) {
for (const block of result.data.blocks) {
if (!block.editable) {
console.log(`${block.path} is opaque: ${block.opaqueReason}`);
}
}
}
Read a page's structure
PageStructure is the whole page as the builder sees it.
| Field | Type | Description |
|---|---|---|
page | PageMeta | The metadata of the page. |
blocks | BlockNode[] | The top-level blocks, each carrying its own children. |
queries | QueryStructure[] | The query routes declared on the page, found by shape. Queries describes them. |
version | string | A content hash of the page file. |
version makes a write conditional. Pass it back as expectedVersion on the next mutation, and the operation fails with stale if the file changed in between. Results and errors describes stale.
Read the listings
ListPages and ListCategories return summaries instead of full structures, so a caller can survey a project without the structure of every page.
PageSummary:
| Field | Type | Description |
|---|---|---|
ref | PageRef | The page's route string. |
id | string | The page id. |
displayName | string | The label shown in the menu. |
category | CategoryRef | The category the page belongs to. |
moduleId | string | The module option of the page, for a page that declares one. |
filepath | string | The file the page is declared in. |
icon | string | The icon the menu shows beside the page, when it declares one. |
order | number | Sorts the page among the others of its category, when it declares one. |
hidden | boolean | Whether the menu leaves the page out. Its route still answers. |
sourceModule | string | The project module the page lives in, when it is not the project's own module. |
CategorySummary:
| Field | Type | Description |
|---|---|---|
ref | CategoryRef | The category's id. |
displayName | string | The label shown in the menu. |
parent | CategoryRef | The parent category, absent for a root. |
icon | string | The icon name, when the category declares one. |
order | number | Its place among its siblings in the menu, lowest first, when the category declares one. |
import {
ListCategories,
ListPages,
} from "@antelopejs/interface-dms-builder";
const [pages, categories] = await Promise.all([
ListPages(),
ListCategories(),
]);
const rootPages = pages.filter((page) => page.category === "pages");
Patch a category's metadata
EditableCategoryMeta is what ConfigureCategory accepts. Its fields are displayName, parent, icon and order. ConfigureCategory refuses a new parent with unsupported, because every page beneath the category would change route at once. Configure a category lists the refusals.
import type { EditableCategoryMeta } from "@antelopejs/interface-dms-builder";
const patch: Partial<EditableCategoryMeta> = { displayName: "Reports", order: 2 };
Next steps
- Catalog lists the block types and DataTypes the builder can write.