Last indexed: 31 January 2026 (cf9511)

Custom Fields

The Custom Fields system enables dynamic schema extension for existing models without requiring database schema changes. This feature allows administrators to define additional fields for models at runtime, with the field definitions stored in the CustomField database table. The system generates FormKit-compatible schemas that can be consumed by frontend forms.

For information about the base model system and database schema management, see Data Layer. For configuration management through the Config model, see Config Model and Settings.

Overview and Architecture

The Custom Fields system provides a metadata-driven approach to extending model schemas. Field definitions are stored as records in the CustomField table, each specifying properties like field type, validation rules, options, and display order. The system then dynamically generates form schemas that can be rendered by frontend frameworks.

Sources: db.json607-675 src/Type/App.php58-90 src/Type/App.php212-216

CustomField Database Model

The CustomField table stores metadata for dynamically-defined fields. Each record represents one custom field definition associated with a specific model.

Column	Type	Purpose
`custom_field_id`	int (PK)	Unique identifier for the custom field
`name`	varchar(100)	Field name used in the data structure
`label`	varchar(100)	Human-readable label displayed in forms
`model`	varchar(45)	Target model class name (indexed)
`type`	varchar(45)	Field type (text, select, checkbox, etc.)
`placeholder`	varchar(100)	Placeholder text for input fields
`options`	json	Available options for select/radio fields
`validation`	varchar(100)	Validation rules to apply
`default_value`	json	Default value for the field
`order`	int	Display order (default: 0)
`help`	varchar(1000)	Help text or description

The model field is indexed to enable efficient queries when retrieving all custom fields for a specific model class. The order field controls the sequence in which fields appear in generated forms.

Sources: db.json607-675

Configuration and Enablement

Custom fields are controlled by a configuration setting that determines which models support dynamic field extension. This provides granular control over which parts of the system can be customized.

Enabling Custom Fields for Models

The custom_field_models configuration value stores a comma-separated list of model class names that support custom fields:

Config.custom_field_models = "User,Product,Order"

The GraphQL query getCustomFieldModels retrieves this list:

This query parses the configuration value and returns an array of model names: ["User", "Product", "Order"].

Sources: src/Type/App.php82-90

Menu Integration

The Custom Fields menu item is conditionally displayed based on whether any models have been configured for custom fields. The menu filtering logic checks for the presence of the custom_field_models configuration:

This ensures that the Custom Fields management interface only appears when the feature is actively configured.

Sources: src/Type/App.php212-216

Field Types and Validation

Custom fields support various field types and validation rules, with configuration stored in JSON format for flexibility.

Field Types

The type column specifies the input control type. Common values include:

text - Single-line text input
textarea - Multi-line text input
select - Dropdown selection
checkbox - Boolean checkbox
radio - Radio button group
date - Date picker
number - Numeric input

Options Structure

For fields that require predefined choices (select, radio, checkbox groups), the options JSON field stores the available values. Example structure:

Validation Rules

The validation field stores validation rule identifiers or expressions that can be interpreted by the frontend validation system. Examples:

required - Field must have a value
email - Must be valid email format
min:5 - Minimum length or value
max:100 - Maximum length or value

Default Values

The default_value JSON field stores the initial value for new records. For simple fields, this might be a string or number; for complex fields like multi-select, it could be an array.

Sources: db.json607-675

FormKit Schema Generation

The system generates FormKit-compatible schemas dynamically by querying custom field definitions for a specific model. FormKit is a form-building library that uses schema-based configuration.

GraphQL Query Interface

The getCustomFieldSchema query accepts a model name and returns an array of FormKit schema objects:

Schema Generation Process

The implementation src/Type/App.php58-79 follows these steps:

Initialize an empty schemas array
Query the CustomField table filtering by the model parameter: CustomField::Query(["model" => $model])
Iterate through each CustomField record
Call getFormKitSchema() on each CustomField instance
Append the resulting schema object to the array
Return the complete array of schemas

FormKit Schema Structure

Each custom field generates a FormKit schema object with the following structure:

The $formkit property specifies the component type (prefixed with l- for Light framework components). The schema object maps directly to FormKit's configuration format, allowing seamless integration with frontend forms.

Sources: src/Type/App.php58-79

Model Association and Queries

Custom fields are associated with models through the model column, which stores the class name of the target model. This creates a logical relationship without requiring foreign keys.

Querying Custom Fields by Model

The system uses the indexed model column to efficiently retrieve all custom fields for a specific model:

This query returns all CustomField records where the model matches "User", ordered by the order field (implicitly, or can be explicitly sorted).

Display Order

The order integer field (default: 0) controls the sequence in which custom fields appear in forms. Lower values appear first. This allows administrators to organize custom fields logically:

Sources: db.json654-657 src/Type/App.php63

GraphQL API Access

The Custom Fields system exposes two main GraphQL queries for accessing field definitions and configuration.

Available Queries

Query	Return Type	Authentication	Description
`getCustomFieldSchema(model: String!)`	`[mixed]`	None	Returns FormKit schemas for a model
`getCustomFieldModels()`	`[String]`	None	Returns list of enabled models

Query: getCustomFieldSchema

Retrieves the FormKit schema array for a specific model:

Example response:

Sources: src/Type/App.php58-79

Query: getCustomFieldModels

Retrieves the list of models that have custom fields enabled:

Example response:

This query reads the custom_field_models configuration value and splits it on commas. If no models are configured, it returns an empty array.

Sources: src/Type/App.php82-90

Integration Flow

The complete flow from custom field definition to frontend rendering follows this sequence:

Sources: src/Type/App.php58-90 db.json607-675

Usage Patterns

Backend: Defining Custom Fields

To add a custom field to a model:

Ensure the model is listed in Config.custom_field_models
Create a CustomField record with appropriate properties
Set the model field to the target model class name
Define type, name, label, and other metadata
Use order to control field positioning

Frontend: Rendering Custom Fields

Frontend applications retrieve and render custom fields:

Query getCustomFieldModels() to determine which models support custom fields
For each model, query getCustomFieldSchema(model: "ModelName")
Pass the returned schema array to FormKit
FormKit renders the appropriate input components based on the schema

Data Storage

While the CustomField table defines the field metadata, the actual custom field data values are typically stored:

In JSON columns on the target model (e.g., User.setting or User.metadata)
In separate key-value tables with model/field/value relationships
Through model extensions or traits that handle custom data

The Light framework's CustomField system focuses on schema definition and form generation, leaving data storage implementation to the application layer.