Forms Guide

Learn how to create powerful forms in Appivo using widgets, data binding, and validation.

Form Building Overview

Appivo forms are built by combining:

Creating a Form

Step 1: Design the Layout

1. Navigate to User Interfaces
2. Create or edit a view
3. Add container widgets for structure
4. Organize into logical sections

Step 2: Add Input Widgets

Drag input widgets to capture data:

Step 3: Bind to Data

Connect widgets to model attributes:

Widget: TextField
Property: value
Binding: customer.name

When the user types, the model attribute updates automatically.

Step 4: Add Validation

Configure validation on each widget:

Widget: TextField (Email)
Validations:
  - Required: true
  - Pattern: valid email format
  - Error Message: "Please enter a valid email"

Step 5: Add Submit Button

Add a Button widget to submit the form:

Widget: Button
Label: "Save"
onClick: Save record and navigate to list

Form Layout Patterns

Simple Form

Single-column layout for straightforward data entry:

Panel: Contact Form
├── TextField: First Name
├── TextField: Last Name
├── EmailField: Email
├── PhoneField: Phone
└── Button: Save

Sectioned Form

Organize related fields into sections:

Panel: Personal Information
├── TextField: First Name
├── TextField: Last Name
└── DateField: Birth Date

Panel: Contact Details
├── EmailField: Email
├── PhoneField: Phone
└── TextField: Address

Panel: Preferences
├── Select: Language
├── CheckBox: Newsletter
└── RadioGroup: Contact Method

Panel: Actions
├── Button: Save
└── Button: Cancel

Two-Column Layout

Use FlexContainer or GridContainer:

GridContainer (2 columns)
├── TextField: First Name
├── TextField: Last Name
├── EmailField: Email
├── PhoneField: Phone
├── TextField: City (span 2 columns)

Data Binding

Binding Input Values

Connect widget values to model attributes:

Binding to Related Data

Populate dropdowns from related models:

Widget: Select (Category)
Options Source: Category model
Display Field: name
Value Field: id
Binding: product.category_id

Calculated Fields

Display computed values:

Widget: Label (Total)
Value: order.quantity * order.unit_price
Read-only: true

Validation

Widget-Level Validation

Configure validation on each input widget:

Validation Timing

Cross-Field Validation

Validate one field against another:

Attribute: confirm_password
Validation:
  - Must equal: password
  - Error: "Passwords must match"

Validation Feedback

Configure how errors display:

• Red border on invalid fields
• Error message below field
• Error summary at form top
• Disable submit until valid

Form Submission

Button Actions

Configure what happens when the form submits:

Button: Save
onClick:
  1. Validate all fields
  2. Save record to model
  3. Show success message
  4. Navigate to list view

Using Rules and Actions

For complex form processing, create a Rule:

Rule: Process Order Form
Type: DATA
Trigger: When Order is created

Action 1: SCRIPT
  - Calculate totals
  - Apply discounts
  - Validate inventory

Action 2: SENDMAIL
  - Send confirmation to customer

Action 3: WEBHOOK
  - Notify fulfillment system

Success Handling

After successful submission:

• Show success message or toast
• Navigate to another view
• Reset the form
• Display created record

Error Handling

When submission fails:

• Show clear error message
• Highlight problem fields
• Preserve entered data
• Allow correction and retry

Advanced Form Patterns

Conditional Fields

Show fields based on other values:

Select: Customer Type
Options: Personal, Business

TextField: Company Name
Visible when: customerType = "Business"

TextField: Tax ID
Visible when: customerType = "Business"

Dynamic Options

Load dropdown options based on selection:

Select: Country
Options: [List of countries]

Select: State/Province
Options: Loaded based on selected country
Dependency: Country selection

Multi-Step Forms

Break long forms into steps using TabContainer:

TabContainer: Registration Wizard
├── Tab 1: Account Information
│   ├── EmailField: Email
│   └── PasswordField: Password
├── Tab 2: Personal Details
│   ├── TextField: Name
│   └── DateField: Birth Date
├── Tab 3: Preferences
│   └── CheckBox: Terms
└── Tab 4: Confirmation
    └── Review summary

Inline Editing

Edit records directly in a DataGrid:

DataGrid: Products
Columns:
  - name (editable)
  - price (editable)
  - stock (editable)
Edit Mode: inline
Save: On blur or Enter key

Form Best Practices

Layout

1. Group related fields together
2. Order fields logically
3. Use clear section headings
4. Keep forms as short as possible
5. Use appropriate input types

Labels and Help

1. Use clear, descriptive labels
2. Add placeholder text for hints
3. Provide help text for complex fields
4. Mark required fields clearly
5. Show format expectations

Validation

1. Validate early when possible
2. Show specific error messages
3. Don't block valid input
4. Preserve entered data on errors
5. Summarize all errors clearly

Submission

1. Disable submit during processing
2. Show loading indicator
3. Give clear success feedback
4. Handle errors gracefully
5. Confirm destructive actions

Accessibility

1. Use proper labels (not just placeholders)
2. Ensure keyboard navigation works
3. Maintain logical tab order
4. Provide error announcements
5. Support screen readers

Mobile Forms

For mobile interfaces, use M-prefixed widgets:

Mobile form considerations:

• Stack fields vertically
• Use full-width inputs
• Provide adequate touch targets (44px minimum)
• Use native date/time pickers
• Consider keyboard type for each field

Next Steps

• Validation Guide - Detailed validation patterns
• User Interfaces - Complete UI building guide
• Rules and Actions - Process form submissions