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

Catalog

The block types, DataTypes, reserved field names and declared data sources the builder reports, with the schema of each option.

Overview

The catalog lists what the builder can put on a page. GetCatalog returns a BlockCatalog with every block factory the builder can write, every DataType a form field can use, and the field names a resource may not take. Each entry carries the import the emitter adds and a schema for the options the factory accepts, so a caller can validate a configuration before it writes one.

The type passed to AddBlock is a catalog key. AddBlock fails with unsupported for a type the catalog does not list.

Read the catalog

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

const catalog = await GetCatalog();
const kpi = catalog.blocks.find((block) => block.type === "KpiCard");
const containers = catalog.blocks.filter((block) => block.container);
const dataTypeIds = catalog.dataTypes.map((dataType) => dataType.id);

GetCatalog is a read. It returns a BlockCatalog directly, not an OpResult.

FieldTypeDescription
blocksBlockTypeDescriptor[]Every block factory the builder can write and configure.
dataTypesDataTypeDescriptor[]Every DataType usable as a form field's type.
reservedFieldNamesstring[]Names a resource field may not take.
generatedAtstringThe ISO time at which the builder built the cached catalog. It is also the cache key.

The builder caches the catalog. RefreshSourceIndex without a page in its scope drops that cache, as Refresh the source index describes.

Describe a block type

BlockTypeDescriptor is keyed on type, the export name of the factory.

FieldTypeDescription
typestringThe export name of the factory, such as KpiCard. It is the catalog key and the value of AddBlockInput.type.
importImportRefThe import the emitter adds for the factory.
componentNamestringThe frontend component the factory emits, such as dms-kpi-card.
labelstringThe label for the palette. A consumer falls back to type when it is absent.
iconstringThe icon name for the palette.
groupBlockGroupThe palette section: layout, content, data, visualization, or another name a DMS declares.
containerbooleanWhether the block accepts .child(...).
allowedChildrenstring[]The block types accepted as children. Any type is accepted when it is absent.
slotsSlotDescriptor[]The fixed named regions the block exposes, when it has any.
dynamicSlotsDynamicSlotsWhere the block's own options name its regions, for a container such as Tab.
configConfigSchemaA description of the options object of the factory.
defaultsConfigObjectThe option values the factory applies when the caller omits them.
childMetaConfigSchemaThe schema of the metadata a child carries, such as { colSpan }.
fixedOptionsConfigObjectThe options the factory sets itself whatever the caller passes, such as the type of a chart.
configOriginConfigOriginHow the builder determined the shape of config.
descriptionstringA human-readable description of the block.
controllerArgbooleantrue when the factory takes a controller class as its first argument, before its options object.
initialChildrenBlockInitialChild[]The children a new block of this type starts with, as the DMS's own helper places them in code. A PageToolbar starts with a LiveToggle and a PeriodSelector, with the options of pageToolbar(). Each child has an id (the child id that roles name it by), a type (a catalog key) and its options. Absent for most types.

Only a container block can hold children. Check container before you pass the path of a block as AddBlockInput.parent.

Place a block in a slot

A container block can declare named regions. SlotDescriptor describes one fixed region.

FieldTypeDescription
idstringThe slot id, passed as AddBlockInput.slot.
labelstringThe name of the slot for a person.
descriptionstringWhat the slot is for.
typescript
import { GetCatalog } from "@antelopejs/interface-dms-builder";

const catalog = await GetCatalog();
const descriptor = catalog.blocks.find((block) => block.type === "Card");
const slotIds = descriptor?.slots?.map((slot) => slot.id) ?? [];
// ["actions", "footer"]

Some containers take their regions from their own options instead. Tab names one region per entry of its items option. Its descriptor has no slots and carries dynamicSlots instead.

FieldTypeDescription
optionPathstringThe option of the block config that lists the regions, such as items.
idKeystringThe key of each entry that holds the slot id, such as slot.
labelKeystringThe key of each entry that holds its label, such as label.

Handle a block that takes a controller

Some factories take a controller class before their options, as in TableView(controller, options). Those descriptors carry controllerArg: true, and their config describes the second argument, the options object.

A block type with controllerArg: true requires AddBlockInput.controller, which names the resource whose DataAPI class becomes the first argument. AddBlock fails with invalid_config when that controller is missing, and when a controller is passed for any other block type. Add a block covers both rules.

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

const catalog = await GetCatalog();
const tableView = catalog.blocks.find((block) => block.type === "TableView");
if (tableView?.controllerArg) {
  // AddBlock for this type must carry `controller: "<resource ref>"`.
}

Read a config schema

ConfigSchema is a Record<string, OptionSchema>. It describes the options of a block or a DataType in a shape close to JSON Schema. The keys are option names. Each OptionSchema describes one option with these fields:

  • type is one of string, number, boolean, object, array, record, union or unknown.
  • optional, nullable, description and default describe the value.
  • enum lists the values of a literal union.
  • properties describes a nested object, items the element of an array, and values and keys a record.
  • oneOf lists the branches of a union, and discriminator names the property that tags each branch.
  • prefixItems lists the element shapes of a tuple, and allOf the shapes of an intersection.
  • truncated is true when the value has more structure than the catalog describes.
  • ui tells a builder UI how to present the option, with fields such as label, widget, group and advanced.

On top of these keys, the schema carries DMS extensions in the x- namespace.

KeyMeaning
x-dataType: trueThe value is a DataType instance (new <DataType>(...)), such as the type of a Form field. Pass a DataTypeValue, described in Value encodings.
x-component: trueThe value holds a nested block. Most nesting goes through .child(), which AddBlockInput.parent expresses instead of config.
x-controller: trueThe option receives the DataAPI class of a table, such as the dataApiController of a relation. Its value is a $ref to a resource.
typescript
import { GetCatalog } from "@antelopejs/interface-dms-builder";

const catalog = await GetCatalog();
const form = catalog.blocks.find((block) => block.type === "Form");
const fieldsOption = form?.config.fields; // schema for the `fields` option

Resolve an import

ImportRef is the import the emitter adds when it writes a factory call, a DataType instance or a class reference.

FieldTypeDescription
namestringThe imported symbol, such as KpiCard or DefaultDataTypes.StringType.
modulestringA package specifier, fixed and independent of the emitting file.
targetFilestringAn absolute path that the emitter turns into a specifier relative to the file it writes. The emitter uses it for a reference to a local class, such as a generated resource.

An ImportRef carries one of the two. module names a symbol from a package, and targetFile points at a symbol in the project's own source.

Know where a shape came from

ConfigOrigin is "inferred" | "annotated". A BlockTypeDescriptor reports which one applies to its config.

  • annotated means that the DMS declared the block type for the builder. Its schema carries labels, defaults and widgets. A declared block type replaces the inferred one of the same name.
  • inferred means that the builder read the shape off the TypeScript signature of the factory, for a factory the DMS has not declared. A precise options interface gives a precise schema, and a wide or generic option gives a loose one.

An empty or shallow config on an inferred descriptor means that the builder could not describe the type further. It does not mean that the factory takes no options.

Choose a data type

DataTypeDescriptor describes a DataType that the type of a form field or of a table column can use.

FieldTypeDescription
idstringThe registered id, such as string, number or select.
importImportRefThe import the emitter adds for the DataType class.
configConfigSchemaA description of the options of the DataType.
descriptionstringA human-readable description.

Pass the id as $dataType to write a DataType value, as Value encodings describes. A $dataType that the catalog does not list fails with invalid_config.

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

const catalog = await GetCatalog();
const hasSelect = catalog.dataTypes.some((dataType) => dataType.id === "select");

await AddBlock({
  page: "/customers",
  name: "editor",
  type: "Form",
  config: {
    fields: [
      {
        id: "name",
        label: "Name",
        type: { $dataType: "string" },
      },
    ],
  },
});

Avoid a reserved field name

reservedFieldNames lists the names a resource field may not take. They collide with a route of the generated DataController or a member of the model, and CreateResource and AddField fail with invalid_config on them. The list is _id, model, get, list, select, count, new, edit, delete, archive, restore, exportStart, exportStatus and exportDownload. Read it from the catalog instead of keeping a copy.

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

const catalog = await GetCatalog();
const reserved = new Set(catalog.reservedFieldNames);
const fieldName = reserved.has("status") ? "state" : "status";

Resources covers resource fields.

List the declared data sources

ListDataSources(response?) returns the routes that developers declared beside their own code as something a block may read. It is separate from the catalog, because these sources come and go as modules load. With response, it returns only the sources whose responseKind equals it. It returns a DataSourceDescriptor[] directly, not an OpResult.

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

const sources = await ListDataSources();
const paths = sources.map((source) => source.path);
FieldTypeDescription
idstringThe id of the source.
titlestringThe title of the source.
descriptionstringA description of the source.
responseKindstringThe shape the source answers with, matched against what a block can read.
pathstringThe path a block fetches, as declared.
methodstringThe HTTP method, when the source declares one.
paramsConfigSchemaThe parameters the source takes, described like block options.
period{ from: string; to: string }The query parameters that carry a period, when the source takes one.

The builder never reads or rewrites the code behind a declared source. It knows only what the declaration says.

Next steps

  • Page operations creates pages and categories, and edits the block tree of a page.