[data-reveal]{opacity:1!important;transform:none!important}
AntelopeJS DMS
DocumentationPage operations

Page operations

The operations that list, create, configure, move and delete pages, categories and the blocks of a page, with their inputs and refusals.

Overview

Page operations cover the pages, the categories that hold them, and the block tree inside each page. The reads are ListPages, ListCategories and GetPageStructure. The mutations, such as CreatePage, AddBlock and MoveBlock, rewrite the source and return the list of FileChange entries they wrote.

Every mutation returns an OpResult, so branch on ok before you read data. Addressing and structure describes the refs and shapes these operations take and return. Results and errors describes their errors and warnings.

List pages and categories

ListPages and ListCategories are plain reads. They return arrays, not an OpResult.

typescript
import {
  ListCategories,
  ListPages,
} from "@antelopejs/interface-dms-builder";

const pages = await ListPages();
const categories = await ListCategories();

for (const page of pages) {
  console.log(page.ref, page.displayName, page.filepath);
}

Read a page's structure

GetPageStructure(ref) returns the metadata, the block tree and the queries of the page in an OpResult<PageStructure>. Its changes array is empty, because the operation is a read.

typescript
import { GetPageStructure } from "@antelopejs/interface-dms-builder";

const result = await GetPageStructure("/dashboard");
if (!result.ok) {
  throw new Error(`cannot read /dashboard: ${result.error.code}`);
}

const { page, blocks, queries, version } = result.data;

Keep version. Passed as expectedVersion on the next mutation, it makes the write conditional.

Refresh the source index

The builder keeps an index of the project's source and a cached catalog. Every mutation drops the index after it writes. A read also rescans by itself when a file the index read has changed or disappeared since the scan, after a hand edit or a checkout for example. The index does not see a new file until a file it already read changes, such as the barrel that imports the new file. It never drops the catalog. Call RefreshSourceIndex after such a change, and after a change to the components the catalog describes.

typescript
import { RefreshSourceIndex } from "@antelopejs/interface-dms-builder";

await RefreshSourceIndex();                       // source index and catalog
await RefreshSourceIndex({ page: "/dashboard" }); // source index only

RefreshScope has a single field:

OptionTypeDescription
pagePageRefKeep the cached catalog. Without page, the call drops the catalog as well.

The scope does not narrow the source index. The call drops the whole index either way, and a page only spares the catalog cache. Pass a page when the change touched page source and left the component catalog alone. It saves a rebuild of the catalog, not a rescan of the project.

The call only drops the caches. The next read pays the cost, because it rescans the project in full and keeps the result. Two refreshes in a row cost nothing extra, and a refresh before every read costs a full scan every time. The operation returns void, not an OpResult.

Create a page

CreatePage(input) writes a new page file and wires it into the nearest barrel. It returns the ref it assigned and the file it created. The new page uses DefaultLayout({ fullWidth: true }).

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

const result = await CreatePage({
  name: "revenue",
  displayName: "Revenue",
  category: "pages",
  icon: "i-ph-chart-line",
  description: "Monthly revenue overview",
});
if (result.ok) {
  console.log(result.data.ref, result.data.filepath);
}

CreatePageInput:

OptionTypeDescription
namestringThe page id and route segment. Required. It must be lowercase letters, digits and single dashes, or the call fails with invalid_config. A duplicate fails with duplicate_name.
displayNamestringThe label shown in the menu. Required.
categoryCategoryRefThe category to attach to. Required. An unknown category fails with not_found.
iconstringThe icon name.
ordernumberSort order within the category.
descriptionstringThe page's description.
permissionPagePermissionThe permission guarding the page.
dirstringA folder relative to the src root, which replaces the placement beside the category.
modulestringThe project module to write into, by its id in the project configuration. Without it, the builder writes into the project's own module. The module must be a local module with an src/index.ts, and the page may only use declarations from that same module. A category declared in another module fails with invalid_config.

Without dir, the page goes to <category-folder>/<name>/page.ts when the project's source declares the category and an index.ts barrel sits beside it. Otherwise it goes to src/<name>.ts, next to the root barrel. With dir, it goes to src/<dir>/<name>/page.ts. In each case the builder wires the nearest barrel above the file, which keeps a relative import chain up to src/index.ts. dir must stay inside the src tree. A dir that leaves it, or a project with no barrel to wire, fails with unsupported.

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

await CreatePage({
  name: "revenue",
  displayName: "Revenue",
  category: "pages",
  dir: "reporting", // → src/reporting/revenue/page.ts
});

Configure a page

ConfigurePage(ref, patch, opts?) patches the metadata of the page in place and returns its ref and the version of the page file it wrote. A draft held across the patch saves against that version. The patch is a Partial<EditablePageMeta>. Keys left out stay untouched, and a key set to undefined or null is removed from the options of the page. A key the page reads as absent, such as an icon written as code the builder cannot read, is left as written, because a null there echoes what was read. A page whose options are not a plain object literal fails with unsupported, because the builder needs a literal to rewrite.

typescript
import { ConfigurePage } from "@antelopejs/interface-dms-builder";

const result = await ConfigurePage("/revenue", {
  displayName: "Monthly revenue",
  order: 10,
  hidden: false,
});

Move a page between categories

The category of a page decides its route, so a patch of category moves the page. ConfigurePage rewrites the category option and its import. When the new category has an index.ts barrel beside it, the builder also moves the file to the folder where CreatePage would have put it, and moves the registration with it, so each barrel still lists what its folder holds. The builder rewrites the relative imports inside the page for its new location.

The result carries the new ref of the page, and a route_changed warning names the old one. Nothing redirects the old route, so links and bookmarks to it break.

typescript
import { ConfigurePage } from "@antelopejs/interface-dms-builder";

const moved = await ConfigurePage("/form/revenue", { category: "pages.reports" });
if (moved.ok) {
  console.log(moved.data.ref); // "/reports/revenue"
  for (const warning of moved.warnings ?? []) {
    console.log(warning.code, warning.message); // "route_changed" and its message
  }
}

The builder refuses the move in three cases:

  • The target category is unknown. The call fails with not_found.
  • The target category is built in or not declared in source, so a page cannot reference it. The call fails with unsupported.
  • The destination already holds a page of that name. The call fails with duplicate_name.

opts is a MutationOpts, so expectedVersion makes the write conditional.

Delete a page

DeletePage(ref, opts?) removes the page class, with the constants, imports and generated model methods that only the page used. The builder deletes the file and removes its barrel import only when nothing but imports is left in it, because a hand-written page file can also declare a category that other pages import. opts is a MutationOpts.

typescript
import { DeletePage } from "@antelopejs/interface-dms-builder";

const result = await DeletePage("/revenue", { expectedVersion: version });
if (!result.ok && result.error.code === "stale") {
  // Re-read the page and decide again.
}

Create a category

CreateCategory(input) writes the new category to <name>.category.ts beside the root barrel and imports that file from the barrel. A project with no root barrel fails with unsupported.

typescript
import { CreateCategory } from "@antelopejs/interface-dms-builder";

const result = await CreateCategory({
  name: "reports",
  displayName: "Reports",
  parent: "pages",
  icon: "i-ph-folder",
  order: 3,
});
// result.data.ref === "pages.reports"

CreateCategoryInput:

OptionTypeDescription
namestringThe id segment of the category. Required. It must be lowercase letters, digits and single dashes, or the call fails with invalid_config. A duplicate fails with duplicate_name.
displayNamestringThe label shown in the menu. Required.
parentCategoryRefThe parent category. Omit for a category under the root pages.
iconstringThe icon name.
ordernumberSort order among siblings.
modulestringThe project module to write into, as CreatePageInput.module.

A parent that does not exist fails with not_found.

Configure a category

ConfigureCategory(ref, patch) patches an existing category. It takes no options argument.

typescript
import { ConfigureCategory } from "@antelopejs/interface-dms-builder";

await ConfigureCategory("pages.reports", {
  displayName: "Reporting",
  order: 1,
});

An unknown category fails with not_found. Three refusals fail with unsupported:

  • a patch that carries parent,
  • a category that is built in or not declared in editable source,
  • a category whose options are not a plain object literal.

Delete a category

DeleteCategory(ref) removes the category declaration. When nothing but imports is left in its file, the builder deletes the file and the imports of it.

typescript
import { DeleteCategory } from "@antelopejs/interface-dms-builder";

const result = await DeleteCategory("pages.reports");
if (!result.ok && result.error.code === "referential_integrity") {
  console.log("still in use by", result.error.blockedBy);
}

A category that still holds pages, directly or through its subcategories, or that has child categories, fails with referential_integrity. blockedBy lists the refs of those pages and child categories. A built-in category, or one not declared in editable source, fails with unsupported.

Add a block

AddBlock(input, opts?) writes a factory call into the page and returns the BlockPath of the new block.

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

const result = await AddBlock({
  page: "/revenue",
  name: "total",
  type: "KpiCard",
  config: {
    title: "Total revenue",
    icon: "i-ph-currency-eur",
  },
});
if (result.ok) {
  console.log(result.data.path); // "/revenue#total"
}

AddBlockInput:

OptionTypeDescription
pagePageRefThe page to add to. Required.
namestringThe block's name, unique among its siblings. Required. A duplicate fails with duplicate_name.
typestringA BlockTypeDescriptor.type from the catalog. Required. An unknown type fails with unsupported.
configConfigObjectThe factory's options object. Required.
parentBlockPathThe container to nest under. Omit to add a top-level block.
slotstringThe slot within the parent container.
indexnumberPosition among siblings. Defaults to appending.
metaConfigObjectChild metadata emitted alongside slot in the third argument of .child(), such as { colSpan: 2 }. Ignored for top-level blocks.
controllerResourceRefThe resource whose DataAPI class is the leading argument, for controller-leading block types.

config is plain JSON by default. A value that is not a literal, such as a DataType instance or a reference to a generated class, uses the encodings in Value encodings.

A nested block needs an editable container. A parent that resolves to an opaque block fails with opaque_target, and a parent that does not resolve fails with not_found. The builder clamps an index out of range, and the result carries an index_clamped warning.

A block type whose catalog entry has controllerArg: true, such as TableView, requires controller. Any other type refuses it. Both mismatches fail with invalid_config.

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

await AddBlock({
  page: "/products",
  name: "table",
  type: "TableView",
  controller: "product", // emitted as the imported productDataAPI class
  config: { caption: "Products" },
});

Configure a block

ConfigureBlock(path, patch, opts?) rewrites the options object of a block. By default the patch merges. Listed keys are replaced, other keys stay, and a key set to undefined is removed.

typescript
import { ConfigureBlock } from "@antelopejs/interface-dms-builder";

await ConfigureBlock("/revenue#total", {
  title: "Revenue (net)",
  description: undefined, // removes the option
});

ConfigureBlockOpts extends MutationOpts:

OptionTypeDescription
replacebooleanReplace the whole options object instead of merging into it.
expectedVersionstringThe PageStructure.version you last read. A mismatch fails with stale.
metaConfigObjectA patch of the child metadata, such as slot or colSpan. A key set to undefined is removed. A top-level block has no .child() call to carry it, so it fails with unsupported.

The following example reads the version before it changes an existing child. /revenue#grid/total must already be a child of the grid of the page.

ts
import { ConfigureBlock, GetPageStructure } from "@antelopejs/interface-dms-builder";

export async function resizeRevenueCard() {
  const read = await GetPageStructure("/revenue");
  if (!read.ok) return read;

  return ConfigureBlock(
    "/revenue#grid/total",
    { title: "Revenue" },
    { expectedVersion: read.data.version, meta: { colSpan: 2 } },
  );
}

An opaque block fails with opaque_target, because the builder can read it but cannot rewrite it.

Move a block

MoveBlock(path, dest, opts?) moves a child block within its container or into another one.

typescript
import { MoveBlock } from "@antelopejs/interface-dms-builder";

await MoveBlock("/revenue#grid/row/total", {
  parent: "/revenue#grid/footer",
  index: 0,
});

MoveDest:

OptionTypeDescription
parentBlockPathThe destination container. Optional in the type, and required by the operation.
slotstringDeclared in the type, but MoveBlock does not read it. The block lands among the destination's children.
indexnumberPosition among the destination's children. Required.

The path must address a nested block. A top-level block, or a destination without a parent, fails with unsupported. The builder clamps an index out of range and adds an index_clamped warning. An opaque destination fails with opaque_target, and a missing one fails with not_found.

Remove a block

RemoveBlock(path, opts?) deletes a block. The builder removes a top-level block as a static member, and drops a nested one from the .child() chain of its parent.

typescript
import { RemoveBlock } from "@antelopejs/interface-dms-builder";

const result = await RemoveBlock("/revenue#grid/row/total");
if (result.ok) {
  console.log(result.changes.map((change) => change.path));
}

Next steps

  • Resources generates the tables and DataAPI controllers a page reads from.
  • Drafts and preview writes the whole block tree of a page in one transaction.