Form Handling Example

Learn to create forms with validation, conditional fields, and data processing.

What You'll Build

A customer registration form with:

• Required field validation
• Format validation (email, phone)
• Conditional fields based on customer type
• Multi-step form wizard

Prerequisites

• Completed the Hello World example
• Understanding of widgets and data binding

Step 1: Create the Customer Model

Define the data structure:

Step 2: Build a Basic Form

Create the registration view:

Panel: Customer Registration
├── RadioGroup: Customer Type
│   Options: Personal, Business
│   Bound to: customer_type
│
├── Panel: Personal Information
│   ├── TextField: First Name
│   │   Bound to: first_name
│   │   Required: true
│   ├── TextField: Last Name
│   │   Bound to: last_name
│   │   Required: true
│   ├── EmailField: Email
│   │   Bound to: email
│   │   Required: true
│   └── PhoneField: Phone
│       Bound to: phone
│
├── Panel: Address
│   ├── TextField: Street Address
│   ├── TextField: City
│   └── Select: Country
│       Required: true
│
└── FlexContainer: Actions
    ├── Button: Register
    └── Button: Cancel

Step 3: Add Validation

Required Fields

Configure each required widget:

TextField: First Name
Properties:
  required: true
  errorMessage: "First name is required"

Format Validation

For email and phone:

EmailField: Email
Properties:
  required: true
  pattern: Standard email format
  errorMessage: "Please enter a valid email address"

PhoneField: Phone
Properties:
  pattern: International phone format
  errorMessage: "Please enter a valid phone number"

Custom Validation

Terms acceptance:

CheckBox: Terms Accepted
Properties:
  required: true
  errorMessage: "You must accept the terms to continue"

Step 4: Add Conditional Fields

Show business fields only for business customers:

Business Fields Panel

Panel: Business Information
Visible when: customer_type = "Business"
├── TextField: Company Name
│   Bound to: company_name
│   Required: true (when visible)
└── TextField: Tax ID
    Bound to: tax_id
    Required: true (when visible)

Visibility Configuration

Panel: Business Information
Visibility Condition: customer_type equals "Business"

When the user selects "Business", the panel appears. When they select "Personal", it hides.

Step 5: Create Multi-Step Form

For long forms, use a TabContainer as a wizard:

TabContainer: Registration Wizard
├── Tab 1: Account Type
│   ├── RadioGroup: Customer Type
│   └── Button: Next
│
├── Tab 2: Personal Details
│   ├── TextField: First Name
│   ├── TextField: Last Name
│   ├── EmailField: Email
│   ├── PhoneField: Phone
│   └── FlexContainer
│       ├── Button: Back
│       └── Button: Next
│
├── Tab 3: Business Details (visible if Business)
│   ├── TextField: Company Name
│   ├── TextField: Tax ID
│   └── FlexContainer
│       ├── Button: Back
│       └── Button: Next
│
├── Tab 4: Address
│   ├── TextField: Street
│   ├── TextField: City
│   ├── Select: Country
│   └── FlexContainer
│       ├── Button: Back
│       └── Button: Next
│
└── Tab 5: Confirmation
    ├── Summary of all entered data
    ├── CheckBox: Terms Accepted
    ├── CheckBox: Newsletter
    └── FlexContainer
        ├── Button: Back
        └── Button: Submit

Step Navigation Logic

Button: Next
onClick:
  1. Validate current step fields
  2. If valid, go to next tab
  3. If invalid, show errors

Button: Back
onClick:
  1. Go to previous tab

Button: Submit
onClick:
  1. Validate terms accepted
  2. Create Customer record
  3. Show success message
  4. Navigate to confirmation page

Step 6: Add Form Processing

Create a Rule to process the registration:

Rule: Process Customer Registration
Type: DATA
Trigger: When Customer is created

Action 1: SCRIPT
  // Set defaults
  if (!record.newsletter) {
    record.newsletter = false;
  }
  record.status = 'Active';
  record.registered_at = new Date();

Action 2: SENDMAIL
  To: record.email
  Template: Welcome Email
  Data:
    name: record.first_name
    customer_type: record.customer_type

Validation Patterns

Cross-Field Validation

Password confirmation example:

TextField: Password
TextField: Confirm Password
  Validation: Must equal Password field
  Error: "Passwords must match"

Conditional Required

Make fields required based on conditions:

TextField: Company Name
Required if: customer_type = "Business"

Date Range Validation

DateField: Start Date
DateField: End Date
  Validation: Must be after Start Date
  Error: "End date must be after start date"

Error Handling

Display Errors

Configure error display:

Form Configuration:
  Error Display: Inline (below each field)
  Highlight: Red border on invalid fields
  Focus: Auto-focus first error field
  Summary: Show error count at form top

Error Messages

Write helpful error messages:

Complete Form Structure

Customer Registration
├── Model: Customer
│   └── Attributes with validation rules
│
├── View: Registration Form
│   ├── Step 1: Customer Type
│   ├── Step 2: Personal Info
│   ├── Step 3: Business Info (conditional)
│   ├── Step 4: Address
│   └── Step 5: Confirmation
│
└── Rule: Process Registration
    ├── Action: Set defaults
    └── Action: Send welcome email

Best Practices

User Experience

1. Show validation errors immediately
2. Don't clear valid data on errors
3. Focus on first error field
4. Disable submit while processing
5. Show loading state during submission

Validation

1. Validate on blur for complex fields
2. Validate on submit for simple forms
3. Use specific, helpful error messages
4. Mark required fields visually

Conditional Fields

1. Hide fields that don't apply
2. Clear hidden field values
3. Adjust validation for visible fields
4. Show/hide smoothly (animation)

Next Steps

• Validation Guide - Advanced validation patterns
• Forms Guide - Complete forms reference
• Rules and Actions - Form processing automation