webiny-api-cms-custom-field-type

# Custom CMS Field Type ## TL;DR A custom field type is a class that extends `DataFieldBuilder<"yourType">`, paired with a factory class implementing `FieldType.Factory`. Register the factory with `container.register(YourFieldType)`. Add a module augmentation on `"webiny/api/cms/model"` so the `fields` registry method gets TypeScript autocomplete. ## When to Use This Use a custom field type when: - You need a field with a storage format or validation logic not covered by the built-in types (`text`, `number`, `boolean`, `datetime`, `file`, `ref`, `object`, `richText`, `longText`, `json`, `dynamicZone`) - You want to expose a fluent builder API (e.g., `fields.slug()`, `fields.color()`) in `ModelFactory` implementations ## Field Type Structure A custom field type consists of three parts: 1. **Builder interface** — extends `DataFieldBuilder<"type">` plus `FieldTypeValidator.*` types 2. **Builder class** — implements the interface, calls `this.validation()` for each validator 3. **Factory class** — implements `FieldType.Factory`, creates builder instances As a standalone extension (not part of a larger feature), the directory layout is: ``` extensions/ └── SlugFieldType/ ├── SlugFieldType.ts # builder interface, builder class, factory class └── feature.ts # createFeature — registers the factory into the DI container ``` `feature.ts`: ```ts // extensions/SlugFieldType/feature.ts import { createFeature } from "webiny/api"; import { SlugFieldType } from "./SlugFieldType.js"; export const SlugFieldTypeFeature = createFeature({ name: "SlugFieldType", register(container) { container.register(SlugFieldType); } }); ``` Register in the API entry point: ```ts // api/Extension.ts import { createFeature } from "webiny/api"; import { SlugFieldTypeFeature } from "~/extensions/SlugFieldType/feature.js"; export const Extension = createFeature({ name: "MyExtension", register(container) { SlugFieldTypeFeature.register(container); } }); ``` ## Complete Example ```ts // extensions/SlugFieldType/SlugFieldType.ts import { DataFieldBuilder, FieldType } from "webiny/api/cms/model"; import type { FieldTypeValidator } from "webiny/api/cms/model"; // 1. Builder interface — extends DataFieldBuilder + desired FieldTypeValidator types export interface ISlugFieldBuilder extends DataFieldBuilder<"slug">, FieldTypeValidator.Required, FieldTypeValidator.Pattern, FieldTypeValidator.Unique {} // 2. Module augmentation — adds fields.slug() to the registry declare module "webiny/api/cms/model" { interface IFieldBuilderRegistry { slug(): ISlugFieldBuilder; } interface IFieldRendererRegistry { myCustomRenderer: { fieldType: "text" | "number"; settings: undefined; }; } } // 3. Builder class — implements each validator method via this.validation() class SlugFieldBuilder extends DataFieldBuilder<"slug"> implements ISlugFieldBuilder { constructor() { super("slug"); } required(message?: string): this { return this.validation({ name: "required", message: message || "Value is required.", settings: {} }); } pattern(regex: string, flags = "", message?: string): this { return this.validation({ name: "pattern", message: message || "Invalid value.", settings: { preset: "custom", regex, flags } }); } unique(message?: string): this { return this.validation({ name: "unique", message: message || "Value must be unique.", settings: {} }); } } // 4. Factory class — implements FieldType.Factory class SlugFieldTypeFactory implements FieldType.Factory { readonly type = "slug"; create(): ISlugFieldBuilder { return new SlugFieldBuilder(); } } // 5. Export as a FieldType implementation export const SlugFieldType = FieldType.createImplementation({ implementation: SlugFieldTypeFactory, dependencies: [] }); ``` ## Using the Custom Field in a Model After registration, `fields.slug()` is available in any `ModelFactory` implementation: ```ts import { ModelFactory } from "webiny/api/cms/model"; class ProductModelImpl implements ModelFactory.Interface { async execute(builder: ModelFactory.Builder) { return [ builder .public({ modelId: "product", name: "Product", group: "ungrouped" }) .fields(fields => ({ name: fields.text().label("Name").required(), slug: fields .slug() .label("Slug") .required("Slug is required.") .unique() .pattern("^[a-z0-9-]+$", "", "Only lowercase letters, numbers, and hyphens.") })) .layout([["name", "slug"]]) .titleFieldId("name") .singularApiName("Product") .pluralApiName("Products") ]; } } ``` ## DataFieldBuilder API All methods return `this` for chaining. | Method | Description | | --------------------------- | --------------------------------------------- | | `label(text)` | Field label shown in the Admin editor | | `help(text)` | Help text shown below the field | | `description(text)` | Field description | | `fieldId(id)` | Override the auto-derived field ID | | `storageId(id)` | Override the storage identifier | | `placeholder(text)` | Placeholder text for the input | | `defaultValue(value)` | Default value for new entries | | `list()` | Make the field accept multiple values (array) | | `listMinLength(n, msg?)` | Minimum number of list items | | `listMaxLength(n, msg?)` | Maximum number of list items | | `tags(tags)` | Arbitrary tags for filtering/querying | | `renderer(name, settings?)` | Set the Admin UI renderer | | `settings(settings)` | Set arbitrary field settings | ### Protected Methods (for use inside validator implementations only) | Method | Description | | --------------------------- | ------------------------------------------------------------------ | | `this.validation(rule)` | Append a `CmsModelFieldValidation` to the field's validation array | | `this.listValidation(rule)` | Append a `CmsModelFieldValidation` to the list validation array | A `CmsModelFieldValidation` has the shape: ```ts { name: string; // validator name (e.g., "required", "minLength", "pattern") message: string; // error message shown to the user settings: Record<string, any>; // validator-specific config } ``` ## Available Validators Import via `import type { FieldTypeValidator } from "webiny/api/cms/model"` and extend your builder interface with them. Each type adds one method to your interface: | Type | Method signature | | ----------------------------------- | ---------------------------------- | | `FieldTypeValidator.Required` | `required(message?)` | | `FieldTypeValidator.Unique` | `unique(message?)` | | `FieldTypeValidator.MinLength` | `minLength(value, message?)` | | `FieldTypeValidator.MaxLength` | `maxLength(value, message?)` | | `FieldTypeValidator.Pattern` | `pattern(regex, flags?, message?)` | | `FieldTypeValidator.Email` | `email(message?)` | | `FieldTypeValidator.Url` | `url(message?)` | | `FieldTypeValidator.LowerCase` | `lowerCase(message?)` | | `FieldTypeValidator.UpperCase` | `upperCase(message?)` | | `FieldTypeValidator.LowerCaseSpace` | `lowerCaseSpace(message?)` | | `FieldTypeValidator.UpperCaseSpace` | `upperCaseSpace(message?)` | | `FieldTypeValidator.Gte` | `gte(value, message?)` | | `FieldTypeValidator.Lte` | `lte(value, message?)` | | `FieldTypeValidator.DateGte` | `dateGte(value, message?)` | | `FieldTypeValidator.DateLte` | `dateLte(value, message?)` | | `FieldTypeValidator.ListMinLength` | `listMinLength(value, message?)` | | `FieldTypeValidator.ListMaxLength` | `listMaxLength(value, message?)` | When implementing a validator method in the builder class, call `this.validation()` with the appropriate `name` and `settings`. For `ListMinLength`/`ListMaxLength`, call `this.listValidation()` instead. The `settings` shapes: | Validator | `name` | `settings` | | ---------------------------- | ----------------------------- | ---------------------------------------------------------------------------- | | Required, Unique | `"required"` / `"unique"` | `{}` | | MinLength, MaxLength | `"minLength"` / `"maxLength"` | `{ value: String(n) }` | | Gte, Lte | `"gte"` / `"lte"` | `{ value: String(n) }` | | DateGte, DateLte | `"dateGte"` / `"dateLte"` | `{ value }` | | Pattern | `"pattern"` | `{ preset: "custom", regex, flags }` | | Email | `"pattern"` | `{ preset: "email", regex: null, flags: null }` | | Url | `"pattern"` | `{ preset: "url", regex: null, flags: null }` | | LowerCase / UpperCase / etc. | `"pattern"` | `{ preset: "lowerCase"` / `"upperCase"` / etc., `regex: null, flags: null }` | ## Key Rules 1. **`type` string must be unique** — the factory's `readonly type` must not collide with any built-in type (`text`, `number`, `boolean`, `datetime`, `file`, `ref`, `object`, `richText`, `longText`, `json`, `dynamicZone`) or other custom types. 2. **Module augmentation target** — augment `"webiny/api/cms/model"` using `namespace FieldBuilderRegistry { interface Interface { yourType(): IYourFieldBuilder; } }`. 3. **`validation()` is protected** — never call it from outside the builder class. Expose validators as named methods on the interface (e.g., `required()`, `minLength()`). 4. **`dependencies: []`** — field type factories have no DI dependencies; always pass an empty array. 5. **Registration order** — register custom `FieldType` implementations before `FieldBuilderRegistry` is resolved (i.e., in the same `register()` call or before it runs). The registry collects all `FieldType` instances at construction time. ## Related Skills - **webiny-api-cms-content-models** — Using the model builder's fluent API to define CMS models - **webiny-api-cms-catalog** — Full catalog of CMS abstractions including `ModelFactory`, `FieldType`, `DataFieldBuilder` - **webiny-dependency-injection** — The `createImplementation` pattern and DI scoping