Value encodings
How the builder writes a configuration value to source: plain JSON as a literal, and the $dataType, $ref, $expr and $block sentinels for values that must reach the source as TypeScript.
Overview
Configuration values are plain JSON by default. The builder writes AddBlockInput.config, a ConfigureBlock patch and a page's permission to source exactly as you pass them, as literals.
The type of such a value is ConfigValue. It is a string, a number, a boolean, null, undefined, an array of ConfigValue items, or a ConfigObject, an object whose members are ConfigValue items. The compiler refuses a function or a class instance. undefined stands for an absent member. The builder skips it when it writes, and a ConfigureBlock patch reads it as "remove this key". The four encodings below are ConfigObject values.
Some options need TypeScript values instead of JSON literals. A form field needs a DataType instance, a relation needs a controller class, and a chart card needs a nested chart. The structured encodings below let the builder write those values and their imports. A raw $expr is the fallback for anything else, and page drafts and query parameters refuse it.
import type {
BlockValue,
DataTypeValue,
ExprValue,
RefValue,
} from "@antelopejs/interface-dms-builder";
Choose an encoding
| You are writing | Encoding |
|---|---|
| A string, number, boolean, array or object | The value itself, as JSON. |
A value the catalog marks x-dataType | DataTypeValue |
| A reference to a class of a builder-generated resource | RefValue |
A nested component in an option the catalog marks x-component | BlockValue |
| Anything else that must reach the source as code | ExprValue |
The catalog says which option needs which encoding. An option marked x-dataType in a block's ConfigSchema takes a DataTypeValue and nothing else. See Catalog.
Write a DataTypeValue
DataTypeValue emits new <DataType>(<config>) and adds the import.
| Field | Type | Description |
|---|---|---|
$dataType | string | A DataTypeDescriptor.id from the catalog, such as "string" or "select". |
config | ConfigObject | The DataType's options. Omit it for new <DataType>() with no argument. |
import { AddBlock } from "@antelopejs/interface-dms-builder";
await AddBlock({
page: "/customers",
name: "editor",
type: "Form",
config: {
fields: [
{
id: "name",
label: "Name",
type: { $dataType: "string", config: { placeholder: "Name" } },
},
],
},
});
// emits: type: new DefaultDataTypes.StringType({ placeholder: "Name" })
A resource field's dataType takes the same encoding, as Resources describes.
A $dataType id that the catalog does not list fails with invalid_config. The message names GetCatalog as the source of the valid ids.
Reference a generated class
RefValue emits the bare class name of a builder-generated resource and adds its import. It is the checked alternative to ExprValue for a class reference, such as the dataApiController of a RelationType.
| Field | Type | Description |
|---|---|---|
$ref.resource | string | A ResourceRef, the resource's name, such as "product". |
$ref.as | "dataApi" | "table" | "model" | Which of the resource's classes to reference. Defaults to "dataApi". |
import { AddField } from "@antelopejs/interface-dms-builder";
await AddField("order-line", {
name: "productId",
label: "Product",
dataType: {
$dataType: "relation",
config: { dataApiController: { $ref: { resource: "product" } } },
},
});
// emits: dataApiController: productDataAPI (imported from the resource's data-api.ts)
as picks one of the three classes a resource generates. "dataApi" is the DataController, "table" is the Table and "model" is the BasicDataModel. An unknown resource fails with invalid_config, and the message names ListResources as the source of the valid refs.
AddBlockInput.controller holds the same reference in a field of its own. A block type that leads with a controller takes a ResourceRef there, not a RefValue in its config. See Page operations.
Write a raw expression
The builder emits an ExprValue as written. It is for a value the builder cannot model as structure.
| Field | Type | Description |
|---|---|---|
$expr | string | TypeScript source, inserted into the emitted file as written. |
import { ConfigureBlock } from "@antelopejs/interface-dms-builder";
await ConfigureBlock("/revenue#total", {
valueFormat: { $expr: "REVENUE_FORMAT" },
});
Two constraints apply:
- The symbol the expression names must already be in scope in the target file.
$expradds no import. - A query's parameters refuse
$expr, because a query's values are data and a raw expression would put code the builder cannot check inside a model body. See Queries.
A consumer that runs the builder in a restricted mode can refuse $expr entirely, because arbitrary code removes the checks that the structured encodings give. RefValue and BlockValue stay allowed in that mode, because the builder checks them. For a generated class, RefValue is the encoding to use.
Nest a block in a config value
A few options hold a component instead of data, such as the chart of a ChartCard, which the catalog marks x-component. BlockValue writes such a component. The builder emits the nested factory call and adds its import.
import type { BlockValue } from "@antelopejs/interface-dms-builder";
const chart: BlockValue = {
$block: { type: "ChartArea", config: { xaxisType: "datetime" } },
};
// emits: chart: ChartArea({ xaxisType: "datetime" })
type is a catalog key, like AddBlockInput.type. In a page draft, an unknown type fails with invalid_config. AddBlock and ConfigureBlock do not turn it into a result, and the call rejects with an unknown block type error. Read-back mirrors the write. A nested factory call whose callee is a known block type reads back as a $block sentinel, not as $expr, so the value stays editable.
Most nesting does not go through config. It goes through .child, which AddBlockInput.parent or BlockDraft.children express. $block is only for an option that the catalog marks x-component.
Next steps
- Results and errors shows how to branch on an operation's result and read its diagnostics.