Forms

Overview

The Form Builder is a comprehensive form creation and management system that enables tenant administrators to build complex forms with a drag-and-drop interface, collect submissions, and manage data with advanced features like multi-step forms, conditional logic, and MTE encryption.

Implementation Status

Overall Progress: ~85% Complete

Core Features ✅

• Drag-and-drop field builder with properties panel
• 15+ field types including signatures and photo capture
• Multi-step forms with navigation
• Mobile-responsive public forms
• Submission management with export
• Template library
• MTE Relay encryption

In Development ⏳

• URL variables and calculated fields
• Conditional logic (if/then rules)
• Private form authentication
• Webhook integration
• Email notifications
• SPAM protection

Field Types

Input Fields

• Text: plain, area, email, phone, password, url
• Number: min, max, decimal, integer support
• Date: calendar picker with manual input
• File(s): single or multiple file uploads
• Digital Signature: canvas-based signature capture
• Photo Capture: camera integration for photos

Selection Fields

• Checkbox: checkbox group, toggle switches
• Radio: single-select radio buttons
• Select: dropdown with single selection
• Multi-Select: multiple selection dropdown

Content Fields

• HTML: WYSIWYG editor for rich content
• Decorators: h1, h2, h3, paragraph, separator, image
• Checklist: complex table-based checklists

Form Properties

• Basic: Title, description, slug
• Branding: Theme color customization
• Layout: Single/multi-step, multi-column layouts
• Visibility: Public, private, account-only modes
• Security: MTE Relay encryption toggle
• Periodicity: Daily, weekly, monthly submission limits

Routes

Admin Routes

• /app/{tenant}/admin/forms - List all forms
• /app/{tenant}/admin/forms/new - Create new form
• /app/{tenant}/admin/forms/{id} - Edit form builder
• /app/{tenant}/admin/forms/{id}/settings - Form configuration
• /app/{tenant}/admin/forms/{id}/submissions - View submissions

Public Routes

• /f/{slug} - Public form (no tenant context)
• /{tenant}/f/{slug} - Tenant-scoped public form

API Endpoints

• /api/f/{slug} - Form submission endpoint
• /api/{tenant}/f/{slug} - Tenant form submission

Database Models

Form Model

model Form {
  id              String   @id @default(cuid())
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
  tenantId        String
  title           String
  slug            String   @unique
  description     String?
  status          String   // "active" | "archived"
  visibility      String   // "public" | "private" | "account-only"
  themeColor      String?
  useMteRelay     Boolean  @default(false)
  fields          String   @db.NVarChar(Max) // JSON
  thankYouMessage String?
  redirectUrl     String?
  submissions     FormSubmission[]
  tags            FormTag[]
}

FormSubmission Model

model FormSubmission {
  id         String   @id @default(cuid())
  createdAt  DateTime @default(now())
  formId     String
  tenantId   String
  data       String   @db.NVarChar(Max) // JSON
  ipAddress  String?
  userAgent  String?
  encrypted  Boolean  @default(false)
}

MTE Relay Encryption

Overview

MTE (MicroToken Exchange) Relay encryption provides end-to-end encryption for form submissions.

Features

• Configurable per form via admin interface
• Automatic "(MTE)" indicator in form title
• URL parameter override for testing (?mte=true)
• Seamless fallback when disabled
• Full support for file uploads

Security Benefits

• End-to-end encryption of form data
• Protection against man-in-the-middle attacks
• Secure transmission of sensitive information
• No performance impact when disabled

Multi-Step Forms

Forms can be organized into multiple steps with:

• Step-by-step navigation
• Progress indicators
• Save & Continue functionality
• State persistence across steps
• Back/Next button controls

Configuration

1. Add step break fields in form builder
2. Configure step titles and descriptions
3. Set validation rules per step
4. Customize navigation buttons

Submission Management

Features

• View all form submissions
• Filter by date range, form, status
• Search within submission data
• Export to CSV/Excel format
• Delete submissions with confirmation
• View individual submission details

Export Options

• CSV: RFC-4180 compliant format
• Excel: XLSX format with formatting
• Custom Fields: Select which fields to export
• Date Range: Export specific time periods

Template Library

Pre-built form templates for common use cases:

• Contact forms
• Feedback surveys
• Event registration
• Job applications
• Support tickets
• Newsletter signup

Template Features

• One-click template selection
• Customizable after selection
• Template preview before applying
• Create custom templates (future)

Best Practices

Form Design

1. Keep It Simple: Only ask for necessary information
2. Use Clear Labels: Make field purposes obvious
3. Group Related Fields: Use multi-column layouts
4. Add Help Text: Provide context where needed
5. Test on Mobile: Ensure responsive design works

Security

1. Enable MTE: For sensitive data collection
2. Set Visibility: Use appropriate access controls
3. Limit Submissions: Configure periodicity settings
4. Add CAPTCHA: Prevent spam (when available)

Performance

1. Optimize Images: Use compressed decorative images
2. Minimize Steps: Balance UX with length
3. Cache Forms: Public forms are cached
4. Lazy Load Files: Only load file fields when needed

Advanced Features

Save & Continue

• Allows users to save progress and return later
• Stores form state in browser localStorage
• Generates unique continuation tokens
• Clears state after successful submission

URL Variables (Planned)

Pre-populate form fields from URL parameters:

/f/contact?locationId=123&userId=456

Conditional Logic (Planned)

Show/hide fields based on user inputs:

• If/then rules
• Field visibility conditions
• Dynamic required fields
• Calculated fields

Webhooks (UI exists, implementation pending)

Trigger external services on submission:

• POST data to external endpoints
• Custom headers and authentication
• Retry logic for failed requests
• Response logging

Troubleshooting

Form Not Submitting

• Check form visibility settings
• Verify MTE configuration if enabled
• Review browser console for errors
• Ensure all required fields are filled

Submissions Not Appearing

• Check form status (active vs archived)
• Verify tenant context
• Review submission filters
• Check database connectivity

MTE Encryption Issues

• Verify MTE is properly configured
• Check browser console for errors
• Test with ?mte=false parameter
• Review server logs for encryption errors

Future Enhancements

• Conditional field logic
• URL parameter auto-population
• Private form authentication
• Webhook execution
• Email notifications to recipients
• Advanced analytics dashboard
• A/B testing for forms
• SPAM protection (reCAPTCHA)
• GDPR consent integration
• API endpoint for external access