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.
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.
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.
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:
| Option | Type | Description |
|---|---|---|
page | PageRef | Keep 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 }).
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:
| Option | Type | Description |
|---|---|---|
name | string | The 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. |
displayName | string | The label shown in the menu. Required. |
category | CategoryRef | The category to attach to. Required. An unknown category fails with not_found. |
icon | string | The icon name. |
order | number | Sort order within the category. |
description | string | The page's description. |
permission | PagePermission | The permission guarding the page. |
dir | string | A folder relative to the src root, which replaces the placement beside the category. |
module | string | The 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.
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.
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.
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.
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.
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:
| Option | Type | Description |
|---|---|---|
name | string | The 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. |
displayName | string | The label shown in the menu. Required. |
parent | CategoryRef | The parent category. Omit for a category under the root pages. |
icon | string | The icon name. |
order | number | Sort order among siblings. |
module | string | The 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.
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.
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.
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:
| Option | Type | Description |
|---|---|---|
page | PageRef | The page to add to. Required. |
name | string | The block's name, unique among its siblings. Required. A duplicate fails with duplicate_name. |
type | string | A BlockTypeDescriptor.type from the catalog. Required. An unknown type fails with unsupported. |
config | ConfigObject | The factory's options object. Required. |
parent | BlockPath | The container to nest under. Omit to add a top-level block. |
slot | string | The slot within the parent container. |
index | number | Position among siblings. Defaults to appending. |
meta | ConfigObject | Child metadata emitted alongside slot in the third argument of .child(), such as { colSpan: 2 }. Ignored for top-level blocks. |
controller | ResourceRef | The 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.
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.
import { ConfigureBlock } from "@antelopejs/interface-dms-builder";
await ConfigureBlock("/revenue#total", {
title: "Revenue (net)",
description: undefined, // removes the option
});
ConfigureBlockOpts extends MutationOpts:
| Option | Type | Description |
|---|---|---|
replace | boolean | Replace the whole options object instead of merging into it. |
expectedVersion | string | The PageStructure.version you last read. A mismatch fails with stale. |
meta | ConfigObject | A 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.
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.
import { MoveBlock } from "@antelopejs/interface-dms-builder";
await MoveBlock("/revenue#grid/row/total", {
parent: "/revenue#grid/footer",
index: 0,
});
MoveDest:
| Option | Type | Description |
|---|---|---|
parent | BlockPath | The destination container. Optional in the type, and required by the operation. |
slot | string | Declared in the type, but MoveBlock does not read it. The block lands among the destination's children. |
index | number | Position 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.
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.