[data-reveal]{opacity:1!important;transform:none!important}
AntelopeJS DMS
DocumentationAddressing and structure

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.

typescript
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.

typescript
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>.

PathWhat it addresses
/dashboard#kpisThe top-level block named kpis on /dashboard
/dashboard#kpis/rowThe .child("row", …) of that block
/dashboard#kpis/row/revenueThe .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>.

typescript
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.

FieldTypeDescription
refPageRefThe page's route string.
idstringThe page id, the first argument of its PageController.
displayNamestringThe label shown in the menu.
iconstringThe icon name, when the page declares one.
categoryCategoryRefThe category the page belongs to.
ordernumberSort order within the category.
descriptionstringThe page's description.
hiddenbooleanWhether the page is hidden from the menu.
permissionPagePermissionThe permission guarding the page.
livePageLiveThe Direct and Pause options of the page, when it is live.
filepathstringThe 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.

typescript
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.

typescript
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.

FieldTypeDescription
pathBlockPathThe block's address.
namestringStatic key for a top-level block, .child() id for a nested one.
typestring | nullThe factory name, or null when it does not resolve.
editablebooleanWhether the builder can edit the options it understands. false marks an opaque block.
opaqueReasonstringWhy the block is opaque. Set when editable === false.
slotstringThe slot the block sits in, when its parent declares slots.
metaConfigObjectChild 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.
configConfigObjectThe options of the block that are literals. Present only when the block is editable.
lockedOptionsRecord<string, string>The top-level options defined by an expression in code, each with the reason it is locked. A save keeps them unchanged.
controllerResourceRefFor 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.
childrenBlockNode[]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.

typescript
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.

FieldTypeDescription
pagePageMetaThe metadata of the page.
blocksBlockNode[]The top-level blocks, each carrying its own children.
queriesQueryStructure[]The query routes declared on the page, found by shape. Queries describes them.
versionstringA 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:

FieldTypeDescription
refPageRefThe page's route string.
idstringThe page id.
displayNamestringThe label shown in the menu.
categoryCategoryRefThe category the page belongs to.
moduleIdstringThe module option of the page, for a page that declares one.
filepathstringThe file the page is declared in.
iconstringThe icon the menu shows beside the page, when it declares one.
ordernumberSorts the page among the others of its category, when it declares one.
hiddenbooleanWhether the menu leaves the page out. Its route still answers.
sourceModulestringThe project module the page lives in, when it is not the project's own module.

CategorySummary:

FieldTypeDescription
refCategoryRefThe category's id.
displayNamestringThe label shown in the menu.
parentCategoryRefThe parent category, absent for a root.
iconstringThe icon name, when the category declares one.
ordernumberIts place among its siblings in the menu, lowest first, when the category declares one.
typescript
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.

typescript
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.