Field Properties & Configuration

Complete reference for configuring fields in Page Designer, covering common properties, validation, conditional logic, and advanced features.

Common Field Properties

Every field in Page Designer accepts the following core properties:

Identity

id (string, required) - Unique identifier for the field
name (string) - Data binding key (preferred over id for data mapping)
type (string, required) - Field type

Display

label (string, required) - Field label shown to users
placeholder (string) - Hint text when field is empty
description (string) - Help text displayed below field
tooltip (string) - Additional help on (?) icon hover
prefix (string) - Text or icon before input (e.g., "$", "kg")
suffix (string) - Text or icon after input (e.g., "%", "USD")

State

defaultValue (any) - Initial value when form loads
required (boolean) - Field must be filled
disabled (boolean) - Non-interactive, grayed out
hidden (boolean) - Not displayed to user but included in data
readOnly (boolean) - Displayed but non-editable

Data

propertyKey (string) - JSON key for data binding (overrides id)
persistent (boolean) - Save value across sessions

Validation

Fields can have validation rules to ensure data quality.

Built-in Validation

{
  "validation": {
    "required": true,
    "minLength": 3,
    "maxLength": 50,
    "pattern": "^[A-Z].*",
    "email": true,
    "url": true,
    "min": 0,
    "max": 100,
    "unique": true,
    "errorMessage": "Invalid format"
  }
}

Properties

Property	Type	Description	Example
`required`	boolean	Field must have a value	`true`
`minLength`	number	Minimum character length	`3`
`maxLength`	number	Maximum character length	`50`
`min`	number	Minimum numeric value	`0`
`max`	number	Maximum numeric value	`100`
`pattern`	regex	Custom validation regex	`^[a-z0-9]+$`
`email`	boolean	Valid email format	`true`
`url`	boolean	Valid URL format	`true`
`unique`	boolean	Unique value in database	`true`
`custom`	string	JavaScript validation function	`return value > 10`
`errorMessage`	string	Custom error message	`"Must be unique"`

Advanced Validation Rules

Use validationRules array for multiple conditions:

{
  "validationRules": [
    {
      "type": "required",
      "message": "This field is required",
      "trigger": "blur"
    },
    {
      "type": "minLength",
      "minLength": 8,
      "message": "Minimum 8 characters",
      "trigger": "change"
    },
    {
      "type": "pattern",
      "pattern": "^[A-Z]",
      "message": "Must start with uppercase",
      "trigger": "blur"
    },
    {
      "type": "custom",
      "customValidation": "return value % 2 === 0 ? true : 'Must be even'",
      "trigger": "blur"
    },
    {
      "type": "comparison",
      "operator": "lessThan",
      "compareField": "maxPrice",
      "message": "Must be less than max price",
      "trigger": "change"
    },
    {
      "type": "async",
      "asyncValidationUrl": "https://api.example.com/validate",
      "asyncMethod": "POST",
      "debounceMs": 300,
      "message": "Value not available",
      "trigger": "blur"
    }
  ]
}

Validation Rule Types

Type	Parameters	Use Case
`required`	`message`, `trigger`	Non-empty validation
`minLength`	`minLength`, `message`	Minimum characters
`maxLength`	`maxLength`, `message`	Maximum characters
`min`	`min`, `message`	Minimum number
`max`	`max`, `message`	Maximum number
`pattern`	`pattern`, `message`	Regex validation
`email`	`message`	Email format
`url`	`message`	URL format
`comparison`	`operator`, `compareField`, `message`	Compare with another field
`custom`	`customValidation`, `message`	JavaScript function
`async`	`asyncValidationUrl`, `method`, `debounceMs`	Server-side validation

Triggers

blur - Validate when field loses focus
change - Validate on every keystroke
submit - Validate only on form submission
realtime - Continuous validation with debounce

Conditional Logic

Show/hide or require fields based on conditions.

Basic Conditional

{
  "conditional": {
    "rules": [
      {
        "when": "userType",
        "operator": "equals",
        "value": "business",
        "action": "show"
      }
    ],
    "conjunction": "AND"
  }
}

Multiple Conditions

{
  "conditional": {
    "rules": [
      {
        "when": "country",
        "operator": "equals",
        "value": "US",
        "action": "show"
      },
      {
        "when": "age",
        "operator": "greaterThan",
        "value": "18",
        "action": "require"
      }
    ],
    "conjunction": "AND"
  }
}

Operators

Operator	Value Type	Example
`equals`	any	`"status" == "active"`
`notEquals`	any	`"status" != "inactive"`
`contains`	string	`"tags" contains "important"`
`notContains`	string	`"tags" not contains "spam"`
`isEmpty`	-	`"notes" is empty`
`isNotEmpty`	-	`"notes" is not empty`
`greaterThan`	number	`age > 18`
`lessThan`	number	`price < 100`
`greaterThanOrEqual`	number	`score >= 80`
`lessThanOrEqual`	number	`score <= 50`

Actions

Action	Effect
`show`	Display the field
`hide`	Hide the field
`require`	Make field required
`unrequire`	Remove required status
`enable`	Enable the field
`disable`	Disable the field

Conjunction

AND - All rules must match (default)
OR - Any rule can match

Nested Conditions Example

{
  "conditional": {
    "rules": [
      {
        "when": "accountType",
        "operator": "equals",
        "value": "premium",
        "action": "show",
        "childRules": [
          {
            "when": "billingCycle",
            "operator": "equals",
            "value": "annual",
            "action": "disable"
          }
        ]
      }
    ]
  }
}

Calculated Fields

Compute field values based on other fields.

Formula-Based Calculation

{
  "calculated": {
    "type": "formula",
    "formula": "unitPrice * quantity",
    "recalculateOn": ["unitPrice", "quantity"],
    "decimalPlaces": 2
  }
}

JavaScript Calculation

{
  "calculated": {
    "type": "javascript",
    "script": "const subtotal = data.unitPrice * data.quantity; return subtotal * (1 + data.taxRate)",
    "recalculateOn": ["unitPrice", "quantity", "taxRate"]
  }
}

Field Transformation

{
  "calculated": {
    "type": "transform",
    "sourceFields": ["firstName", "lastName"],
    "transform": "_sourceValues.map(v => v.toUpperCase()).join(' ')"
  }
}

Calculation Types

Type	Use Case	Example
`formula`	Math expressions	`unitPrice * quantity * taxRate`
`javascript`	Complex logic	Multi-step calculations
`transform`	String manipulation	Format names, concatenate fields
`aggregate`	Summary calculations	Sum, average, count

Available Context Variables

In calculated fields, access other fields:

data - All form data object
values - Alias for data
field - Current field config
previousValue - Previous field value
now() - Current timestamp

Data Source Configuration

Dynamic options loading from API or database.

Static Options

{
  "options": [
    { "label": "Option 1", "value": "opt1" },
    { "label": "Option 2", "value": "opt2" }
  ]
}

API Data Source

{
  "dataSource": {
    "type": "api",
    "method": "GET",
    "url": "https://api.example.com/countries",
    "valueProperty": "code",
    "labelProperty": "name",
    "dataPath": "data.items",
    "lazyLoad": false,
    "searchQueryName": "q",
    "searchRequestDelay": 0.3,
    "timeout": 10000
  }
}

Record Service Data Source

{
  "dataSource": {
    "type": "resource",
    "resourceKey": "customers",
    "valueProperty": "id",
    "labelProperty": "name",
    "filterQuery": "{ 'status': 'active' }",
    "sortQuery": "{ 'name': 1 }"
  }
}

{
  "dataSource": {
    "type": "api",
    "url": "https://api.example.com/cities",
    "dependsOn": ["countryId"],
    "paramMapping": {
      "countryId": "country_id"
    }
  }
}

Parameters

Parameter	Type	Description
`type`	'api'\|'resource'\|'static'	Data source type
`url`	string	API endpoint URL
`method`	'GET'\|'POST'	HTTP method
`valueProperty`	string	Property for option value
`labelProperty`	string	Property for option label
`dataPath`	string	Path to array in response
`lazyLoad`	boolean	Load on demand
`searchQueryName`	string	URL param for search
`searchRequestDelay`	number	Debounce delay (seconds)
`timeout`	number	Request timeout (ms)
`dependsOn`	array	Fields to trigger reload

Styling & Appearance

CSS Class Names

{
  "style": {
    "className": "custom-field-class",
    "width": "100%",
    "margin": "10px 0",
    "padding": "8px",
    "backgroundColor": "#f5f5f5",
    "border": "1px solid #ccc",
    "borderRadius": "4px"
  }
}

Inline Styles

{
  "style": {
    "color": "#333",
    "fontSize": "14px",
    "fontWeight": "500",
    "textTransform": "uppercase",
    "opacity": 0.8
  }
}

Help & Documentation

Enhanced help system for fields.

{
  "helpContent": {
    "title": "What is this field?",
    "content": "This field captures the user's subscription preference. You can use markdown formatting.",
    "mediaUrl": "https://example.com/help-image.png",
    "mediaType": "image",
    "links": [
      {
        "label": "Learn more",
        "url": "https://docs.example.com/subscriptions"
      },
      {
        "label": "FAQ",
        "url": "https://example.com/faq#subscriptions"
      }
    ]
  }
}

Permissions

Field-level access control.

{
  "fieldPermissions": {
    "view": {
      "roles": ["admin", "manager"],
      "users": [123, 456]
    },
    "edit": {
      "roles": ["admin"]
    },
    "delete": {
      "roles": ["admin"]
    }
  }
}

Complete Example

Complex field with all features:

{
  "id": "discount_percent",
  "type": "number",
  "label": "Discount Percentage",
  "placeholder": "Enter 0-100",
  "description": "Percentage discount applied to order",
  "tooltip": "Enter a value between 0 and 100%",
  "prefix": "",
  "suffix": "%",
  "defaultValue": 0,
  "required": false,
  "disabled": false,
  "hidden": false,
  "min": 0,
  "max": 100,
  "step": 0.5,
  "propertyKey": "discount_pct",
  "validation": {
    "min": 0,
    "max": 100,
    "errorMessage": "Discount must be between 0 and 100%"
  },
  "validationRules": [
    {
      "type": "comparison",
      "operator": "lessThanOrEqual",
      "compareField": "maximumDiscount",
      "message": "Cannot exceed maximum discount",
      "trigger": "blur"
    }
  ],
  "conditional": {
    "rules": [
      {
        "when": "orderTotal",
        "operator": "greaterThan",
        "value": "1000",
        "action": "require"
      }
    ]
  },
  "calculated": {
    "type": "formula",
    "formula": "(orderTotal * discountPercent) / 100",
    "recalculateOn": ["orderTotal", "discountPercent"]
  },
  "helpContent": {
    "title": "Applying Discounts",
    "content": "Apply this discount to eligible orders over $1,000."
  },
  "style": {
    "className": "discount-field",
    "width": "150px"
  }
}

Common Patterns

Email with Validation

{
  "type": "email",
  "label": "Email Address",
  "required": true,
  "validation": {
    "email": true,
    "errorMessage": "Please enter a valid email"
  }
}

Phone with Formatting

{
  "type": "phone",
  "label": "Phone Number",
  "countryCode": "+1",
  "inputMask": "(999) 999-9999",
  "required": true
}

Select with Dynamic Options

{
  "type": "select",
  "label": "Country",
  "dataSource": {
    "type": "api",
    "url": "/api/countries",
    "valueProperty": "id",
    "labelProperty": "name"
  }
}

{
  "type": "select",
  "label": "City",
  "dataSource": {
    "type": "api",
    "url": "/api/cities",
    "dependsOn": ["countryId"],
    "paramMapping": { "countryId": "country_id" }
  }
}

Hidden System Field

{
  "type": "hidden",
  "propertyKey": "createdBy",
  "defaultValue": "system",
  "persistent": true
}

Conditional Required Field

{
  "type": "text",
  "label": "Business Name",
  "conditional": {
    "rules": [
      {
        "when": "userType",
        "operator": "equals",
        "value": "business",
        "action": "require"
      }
    ]
  }
}

Calculated Total Field

{
  "type": "number",
  "label": "Order Total",
  "disabled": true,
  "calculated": {
    "type": "formula",
    "formula": "subtotal + tax - discount",
    "recalculateOn": ["subtotal", "tax", "discount"]
  }
}

Common Field Properties​

Identity​

Display​

State​

Data​

Validation​

Built-in Validation​

Properties​

Advanced Validation Rules​

Validation Rule Types​

Triggers​

Conditional Logic​

Basic Conditional​

Multiple Conditions​

Operators​

Actions​

Conjunction​

Nested Conditions Example​

Calculated Fields​

Formula-Based Calculation​

JavaScript Calculation​

Field Transformation​

Calculation Types​

Available Context Variables​

Data Source Configuration​

Static Options​

API Data Source​

Record Service Data Source​

Cascading Dropdown​

Parameters​

Styling & Appearance​

CSS Class Names​

Inline Styles​

Help & Documentation​

Permissions​

Complete Example​

Common Patterns​

Email with Validation​

Phone with Formatting​

Select with Dynamic Options​

Dependent Dropdown (Cascading)​

Hidden System Field​

Conditional Required Field​

Calculated Total Field​