Addressing and Structure

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.

Alongside the refs, this page describes the read shapes the builder hands back: the page metadata it can read and patch, the block tree it resolves from source, and the lightweight summaries the listing operations return. The operations that produce and consume these shapes live in Page Operations.

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 a page's route string, built from its category's slug and the page's own 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: <pageRef>#<name> for a top-level block, then /<childId> for each nesting level below it.

The first segment after # is the static class member the block is declared as; every further segment is the id passed to .child(). AddBlock returns the path of the block it added, so you rarely build one by hand.

Address a Category

CategoryRef is a category's stable id. The three roots are pages, modules and settings; a category created under a parent is addressed by joining them with a dot, so a reports category under pages is pages.reports.

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 is what the builder knows about a page. It comes back inside PageStructure, which GetPageStructure returns.

hidden, permission and live read back like any other field, as long as the page declares them literally. A permission built from a call or a reference — an Action, say — reads back as undefined: the builder reports only what it can also rewrite.

PagePermission mirrors the DMS MenuOptions.permission: a partial permission spec, whose fields are id, title, icon, description, dependencies and defaultGranted. A bare action id is not accepted — the DMS types the option as Partial<Permission> | Action, so a string would be written and then refused by the typecheck gate.

import type { PagePermission } from "@antelopejs/interface-dms-builder";

const permission: PagePermission = {
  id: "reports.export",
  title: "Export reports",
};

The DMS also accepts an Action there. That is a live object rather than data, so it has no encoding in the builder: a page declaring one reads its permission back as undefined.

PageLive mirrors the DMS MenuOptions.live: maxRate, slowRateAfter, rememberKey. Present, even empty ({}), the page is live — its blocks refetch through a Direct / Pause valve its LiveToggle switches; absent, they refetch on every event. Sent as null in a patch, it is taken off.

Patch a Page's Metadata

EditablePageMeta is the subset of PageMeta that ConfigurePage accepts as a patch: displayName, icon, category, order, description, hidden, permission and live. ref, id and filepath are not patchable — they follow from where the page lives.

Patching category moves the page, which changes its ref: the result carries the new one, and a route_changed warning says what the old route was. See Page Operations.

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 a page's tree. The builder resolves each static member and each .child() call it can parse; anything it cannot parse still appears as a node, marked not editable.

An opaque block is one the builder can see but not rewrite — a block behind an unresolved reference, or one produced by a computed expression rather than a direct factory call. Reading it is fine; ConfigureBlock, AddBlock under it and MoveBlock onto it fail with opaque_target, described in Results and Errors.

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.

version is what 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. See Results and Errors.

Read the Listings

ListPages and ListCategories return summaries rather than full structures, so you can survey a project without parsing every page.

PageSummary:

CategorySummary:

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: displayName, parent, icon and order. Re-parenting a category is refused — every page beneath it would change route at once; see Page Operations.

import type { EditableCategoryMeta } from "@antelopejs/interface-dms-builder";

const patch: Partial<EditableCategoryMeta> = { displayName: "Reports", order: 2 };

Next Steps

• Catalog - Discover the block types and DataTypes you can emit