corrad-bp/docs/form-builder/USER_GUIDE.md

Form Builder User Guide

Overview

The Form Builder is a modern, intuitive drag-and-drop interface for creating dynamic forms. Featuring a smart collapsible settings panel, visual grid system, and intelligent component recommendations, it makes form creation accessible to both developers and non-technical users.

For technical implementation details, see the Technical Guide

Interface Overview

Three-Panel Layout

• Left Panel: Component Library with categorized components
• Center Panel: Form Canvas with 12-column grid system
• Right Panel: Smart Collapsible Settings Panel

Key Features

• Smart Settings Panel: Auto-opens when components are selected, collapses to save space
• Visual Grid System: Intuitive width selection with grid previews
• Quick Settings: Inline editing for common properties
• Smart Recommendations: Automatic width suggestions based on field type
• Real-time Preview: See changes instantly as you build

Getting Started

Creating Your First Form

1. Start Building

   • Navigate to the Form Builder
   • Click "New Form" or start with a template
   • The interface loads with an empty canvas

2. Add Components

   • Drag & Drop: Drag any component from the left panel to the canvas
   • Click to Add: Click a component to add it at the end of the form
   • Smart Placement: Components automatically find optimal grid positions

3. Configure Components

   • Auto-Selection: Click any component to select it
   • Quick Settings: The right panel automatically opens with common settings
   • Inline Editing: Edit labels, names, widths, and validation directly
   • Full Settings: Click "Full Settings" for advanced configuration

4. Save & Preview

   • Auto-Save: Changes are saved automatically
   • Preview Mode: Toggle to test your form as users will see it
   • Form Management: Access all saved forms from the header

Smart Settings Panel System

Panel Behavior

• Auto-Open: Automatically expands when you select a component
• Collapsible: Toggle between expanded (320px) and collapsed (48px) states
• Quick Access: Common settings available without opening full modal
• Context-Aware: Shows only relevant settings for each component type

Quick Settings Available

• Label: Component display name
• Field Name: Internal identifier
• Width: S/M/L/XL quick sizing buttons
• Required: Toggle validation
• Placeholder: Hint text (where applicable)

Collapsed State Features

• Component Icon: Visual indicator of selected component type
• Type Badge: Short identifier (TXT, BTN, SEL, etc.)
• Toggle Button: One-click expansion
• Space-Efficient: Only 48px wide when collapsed

Enhanced Grid System

Visual Width Selection

The new grid system replaces technical percentages with intuitive options:

Width Options

• Narrow (25%): Small inputs like age, zip codes, short codes
• Small (33%): Short text fields, city names, grouped inputs
• Medium (50%): Names, phone numbers, paired inputs
• Wide (75%): Addresses, URLs, prominent fields
• Full (100%): Text areas, headings, single-column layouts

Visual Grid Preview

• 12-Column Grid: Mini preview shows exactly which columns your component will occupy
• Active Columns: Highlighted squares show component width
• Current Selection: Visual feedback shows your current choice
• Grid Math: Displays "6 of 12 columns" instead of technical details

Smart Recommendations

The system automatically suggests optimal widths based on component type:

• Narrow Recommended: Number, Date, Time, Color, OTP fields
• Small Recommended: Text inputs
• Medium Recommended: Email, Phone, Password, Select, Masked inputs
• Wide Recommended: URL, File uploads
• Full Recommended: Text areas, Headings, Choice groups, Buttons

Visual Indicators

• Green Ring: Recommended options have green highlighting
• Selection State: Current choice highlighted in blue
• Combined State: Selected + recommended shows green background

Component Library

Basic Inputs

Perfect for collecting simple data:

Text Field

• Single-line text input
• Smart width: Small (33%)
  • Use for: Names, titles, short answers
• Quick settings: Label, name, placeholder, required

Text Area

• Multi-line text input
• Smart width: Full (100%)
• Use for: Comments, descriptions, long text
• Features: Resizable, character limits

Number Field

• Numeric input with validation
• Smart width: Narrow (25%)
• Use for: Age, quantity, prices
  • Features: Min/max limits, step values

Email Field

• Email input with validation
• Smart width: Medium (50%)
• Use for: Contact forms, registration
• Features: Built-in email format validation

Password Field

• Secure password input
• Smart width: Medium (50%)
• Use for: Authentication forms
  • Features: Password masking, strength indicators

Selection Components

For choosing from options:

Select Dropdown

• Single selection from options
• Smart width: Medium (50%)
• Use for: Countries, categories, status
• Features: Search, custom values, option groups

Checkbox Group

• Multiple selection options
• Smart width: Full (100%)
• Use for: Preferences, multiple choices
• Features: Select all option, layout control

Radio Group

• Single choice from group
• Smart width: Full (100%)
  • Use for: Exclusive choices, yes/no questions
• Features: Button or traditional styles

Switch Toggle

• Boolean on/off control
• Smart width: Full (100%)
• Use for: Settings, feature toggles
• Features: Custom labels, default states

Date & Time Components

For temporal inputs:

Date Picker

• Date selection interface
• Smart width: Narrow (25%)
• Use for: Birthdays, deadlines, scheduling
• Features: Date ranges, format options, validation

Time Picker

• Time selection interface
• Smart width: Narrow (25%)
• Use for: Appointments, schedules
• Features: 12/24 hour format, minute intervals

Date & Time

• Combined date and time picker
• Smart width: Medium (50%)
• Use for: Event scheduling, timestamps
• Features: Single field for both values

Advanced Components

Specialized functionality:

File Upload

• Standard file input
• Smart width: Wide (75%)
• Use for: Document uploads, attachments
  • Features: File type restrictions, size limits

File Drop Zone

• Drag & drop upload area
• Smart width: Wide (75%)
• Use for: Multiple files, intuitive uploads
• Features: Visual feedback, progress indicators

OTP Input

• One-time password entry
• Smart width: Narrow (25%)
• Use for: Two-factor authentication
• Features: Auto-focus, numeric only

Masked Input

• Formatted text input
• Smart width: Medium (50%)
• Use for: Phone numbers, SSN, custom formats
• Features: Real-time formatting, validation

Layout Components

Form structure and organization:

Heading

• Section titles and organization
• Smart width: Full (100%)
  • Use for: Form sections, categories
• Features: Multiple heading levels (H1-H6)

Paragraph

• Descriptive text content
• Smart width: Full (100%)
• Use for: Instructions, explanations
• Features: Rich text formatting options

Divider

• Visual section separator
• Smart width: Full (100%)
• Use for: Content organization
• Features: Various visual styles

Button

• Action triggers
• Smart width: Full (100%)
• Use for: Form submission, navigation
• Features: Custom styling, click handlers

Form Configuration Workflows

Quick Settings Workflow (80% of edits)

1. Click any component to select it
2. Settings panel auto-opens on the right
3. Edit common properties inline:
   • Change label text
   • Adjust field width with S/M/L/XL buttons
   • Toggle required validation
   • Set placeholder text
4. Changes apply immediately

Full Settings Workflow (20% of edits)

1. Select component in quick settings panel
2. Click "Full Settings" button
3. Access comprehensive modal with:
   • All component properties
   • Advanced validation rules
   • Visual width selector with grid preview
   • Component-specific options
   • Reset to defaults option

Bulk Operations

• Duplicate: Copy component with "Duplicate" button
• Delete: Remove component with "Delete" button
• Reorder: Drag components to reposition
• Multi-select: Select multiple components for batch operations

Form Templates & Management

Template System

• Blank Form: Start from scratch
• Contact Form: Pre-built contact form
• Survey Form: Multi-question survey template
• Registration Form: User registration template
• Custom Templates: Save your own templates

Form Management

• Auto-Save: Changes saved automatically every 30 seconds
• Version History: Track form changes over time
• Duplicate Forms: Copy existing forms as starting points
• Export/Import: JSON format for form portability
• Form Library: Organize forms by category or project

Process Builder Integration

Workflow Integration

Forms integrate seamlessly with the Process Builder for automated workflows:

1. Create Form: Design your form in Form Builder
2. Save Form: Forms must be saved before use in processes
3. Add to Process: Select saved form in Process Builder Form Task
4. Data Flow: Form submissions become process variables
5. Decision Logic: Use form data in process gateways and conditions

Advanced Integration Features

• URL Parameters: Pre-populate form fields from process variables
• Conditional Logic: Show/hide fields based on process state
• Multi-Step Forms: Split complex forms across multiple process steps
• Data Validation: Cross-reference form data with process requirements

Best Practices

Form Design

1. Start Simple: Begin with essential fields only
2. Use Smart Widths: Trust the width recommendations
3. Group Related Fields: Use consistent widths for grouped fields
4. Logical Flow: Order fields in a natural sequence
5. Mobile-First: Test forms on mobile devices

Grid Layout Optimization

1. Mix Widths: Combine narrow and wide fields effectively
2. Visual Balance: Avoid too many full-width fields in sequence
3. Logical Grouping: Use similar widths for related fields
4. Space Efficiency: Let the system auto-optimize grid placement

User Experience

1. Clear Labels: Use descriptive, action-oriented labels
2. Helpful Placeholders: Provide examples in placeholder text
3. Progressive Disclosure: Use sections for complex forms
4. Validation Feedback: Set appropriate validation rules
5. Success States: Configure clear success messages

Performance Optimization

1. Component Limits: Keep forms under 50 components when possible
2. Conditional Logic: Use sparingly to maintain performance
3. File Uploads: Set reasonable file size limits
4. Auto-Save: Leverage automatic saving features

Accessibility Features

Built-in Accessibility

• Keyboard Navigation: Full keyboard support
• Screen Reader Support: Proper ARIA labels and descriptions
• Focus Management: Clear focus indicators
• High Contrast: Accessible color combinations
• Touch Targets: Mobile-friendly touch targets

Accessibility Best Practices

1. Descriptive Labels: Always provide clear field labels
2. Help Text: Use help text for complex fields
3. Error Messages: Provide clear, actionable error messages
4. Logical Order: Ensure tab order follows visual layout
5. Alternative Text: Provide alt text for any images

Troubleshooting

Common Issues

Panel Not Opening

• Ensure component is properly selected
• Check browser console for JavaScript errors
• Refresh page if panel state becomes stuck

Grid Layout Issues

• Use the optimize layout feature
• Check for invalid width values
• Reset component to default width

Components Not Saving

• Verify internet connection
• Check browser local storage limits
• Try manual save if auto-save fails

Performance Issues

• Reduce number of components
• Simplify conditional logic
  • Clear browser cache

Getting Help

• Documentation: Complete technical guides available
• Examples: Sample forms and templates provided
• Support: Contact support team for assistance
• Community: Join user community forums

JavaScript & Dynamic Calculations

Real-time Calculations

The Form Builder supports powerful JavaScript-based calculations that update in real-time as users interact with your forms. This enables dynamic forms with automatic calculations, conditional logic, and interactive behavior.

Key Features

• Real-time Updates: Calculations execute instantly when users change field values
• onFieldChange Handlers: Trigger custom logic when specific fields change
• setField Function: Programmatically update field values from JavaScript
• Cross-field Dependencies: Create complex relationships between form fields
• Calculation Templates: Pre-built templates for common calculation patterns

Basic Example

// Form with real-time total calculation
onLoad: function() {
    console.log('Form loaded, setting up calculations...');
    
    // Initialize fields
    setField('quantity', 1);
    setField('price', 0);
    setField('total', 0);
}

onFieldChange: function(fieldName, value) {
    console.log('Field changed:', fieldName, '=', value);
    
    if (fieldName === 'quantity' || fieldName === 'price') {
        // Get current values
        const quantity = getField('quantity') || 0;
        const price = getField('price') || 0;
        
        // Calculate and update total
        const total = quantity * price;
        setField('total', total.toFixed(2));
        
        console.log('Updated total:', total);
    }
}

Available JavaScript Functions

setField(fieldName, value)

Updates a form field value and triggers the UI to refresh.

// Set text field
setField('user_name', 'John Doe');

// Set number field
setField('quantity', 5);

// Set calculated field
setField('total', 99.95);

getField(fieldName)

Retrieves the current value of a form field.

const userName = getField('user_name');
const quantity = getField('quantity') || 0; // Default to 0 if empty

onLoad Event Handler

Executes when the form first loads. Use for initialization and setting default values.

onLoad: function() {
    // Set default values
    setField('country', 'USA');
    setField('currency', 'USD');
    
    // Perform initial calculations
    calculateTotals();
}

onFieldChange Event Handler

Executes whenever a user changes a field value. Receives fieldName and new value as parameters.

onFieldChange: function(fieldName, value) {
    switch(fieldName) {
        case 'quantity':
        case 'price':
            updateTotal();
            break;
            
        case 'country':
            updateShippingOptions(value);
            break;
    }
}

Real-world Examples

Invoice Calculator

onLoad: function() {
    // Initialize invoice fields
    setField('quantity', 1);
    setField('unit_price', 0);
    setField('tax_rate', 8.5); // 8.5% tax
    setField('subtotal', 0);
    setField('tax_amount', 0);
    setField('total', 0);
}

onFieldChange: function(fieldName, value) {
    if (['quantity', 'unit_price', 'tax_rate'].includes(fieldName)) {
        const quantity = parseFloat(getField('quantity')) || 0;
        const unitPrice = parseFloat(getField('unit_price')) || 0;
        const taxRate = parseFloat(getField('tax_rate')) || 0;
        
        const subtotal = quantity * unitPrice;
        const taxAmount = (subtotal * taxRate) / 100;
        const total = subtotal + taxAmount;
        
        setField('subtotal', subtotal.toFixed(2));
        setField('tax_amount', taxAmount.toFixed(2));
        setField('total', total.toFixed(2));
    }
}

Conditional Field Logic

onFieldChange: function(fieldName, value) {
    if (fieldName === 'subscription_type') {
        if (value === 'premium') {
            setField('premium_features', 'Available');
            setField('support_level', '24/7 Priority');
        } else {
            setField('premium_features', 'Not Available');
            setField('support_level', 'Standard Business Hours');
        }
    }
}

Age Calculator

onFieldChange: function(fieldName, value) {
    if (fieldName === 'birth_date') {
        const birthDate = new Date(value);
        const today = new Date();
        
        let age = today.getFullYear() - birthDate.getFullYear();
        const monthDiff = today.getMonth() - birthDate.getMonth();
        
        if (monthDiff < 0 || (monthDiff === 0 && today.getDate() < birthDate.getDate())) {
            age--;
        }
        
        setField('age', age);
        
        // Set eligibility based on age
        if (age >= 18) {
            setField('eligible', 'Yes');
        } else {
            setField('eligible', 'No');
        }
    }
}

Best Practices for JavaScript Forms

Performance Optimization

1. Minimize Calculations: Only calculate when necessary fields change
2. Use Default Values: Provide fallbacks for empty fields
3. Debounce Heavy Operations: For complex calculations, consider debouncing
4. Cache Results: Store calculation results when appropriate

Error Handling

onFieldChange: function(fieldName, value) {
    try {
        if (fieldName === 'price') {
            const price = parseFloat(value);
            if (isNaN(price)) {
                console.warn('Invalid price value:', value);
                return;
            }
            
            // Perform calculation
            calculateTotal(price);
        }
    } catch (error) {
        console.error('Error in field change handler:', error);
    }
}

Debugging Tips

1. Use Console Logging: Add console.log statements to track execution
2. Check Field Names: Ensure field names in code match form field names exactly
3. Validate Data Types: Always parse and validate input values
4. Test Edge Cases: Test with empty values, zero, and negative numbers

Form Templates with JavaScript

CSS & JavaScript Test Form

A comprehensive template demonstrating real-time calculations:

Field Structure:

• user_name (Text): User's name
• quantity (Number): Quantity of items
• price (Number): Price per item
• total (Number): Calculated total (read-only)

JavaScript Logic:

onLoad: function() {
    console.log('Form loaded, initializing...');
    setField('user_name', '');
    setField('quantity', 1);
    setField('price', 0);
    setField('total', 0);
}

onFieldChange: function(fieldName, value) {
    console.log('Field changed:', fieldName, '=', value);
    
    if (fieldName === 'user_name') {
        console.log('User name updated to:', value);
    }
    
    if (fieldName === 'quantity' || fieldName === 'price') {
        const quantity = parseFloat(getField('quantity')) || 0;
        const price = parseFloat(getField('price')) || 0;
        const total = quantity * price;
        
        setField('total', total.toFixed(2));
        console.log('Calculated total:', total);
    }
}

Troubleshooting JavaScript Forms

Common Issues

Calculations Not Updating

• Verify field names match exactly (case-sensitive)
• Check browser console for JavaScript errors
• Ensure onFieldChange handler is properly defined
• Confirm form is in preview mode for testing

Initial Values Not Setting

• Make sure onLoad handler is defined
• Check that setField calls use correct field names
• Verify form data structure in browser developer tools

Console Errors

• "getField/setField is not defined": JavaScript engine not properly initialized
• "Cannot read property": Field name doesn't exist or typo in field name
• "Unexpected token": Syntax error in JavaScript code

Debugging Workflow

1. Open Browser Developer Tools (F12)
2. Check Console Tab for error messages
3. Add Debug Logging:

   onFieldChange: function(fieldName, value) {
       console.log('=== Field Change Debug ===');
       console.log('Field:', fieldName);
       console.log('New Value:', value);
       console.log('Current Form Data:', Object.keys(formData));
   
       // Your calculation logic here
   }
   

4. Test in Preview Mode - JavaScript only executes in preview mode
5. Verify Field Names - Use browser inspect element to confirm field name attributes

Advanced Features

Custom Components

• Component Extensions: Add custom component types
• Styling Overrides: Custom CSS for branded forms
• Validation Rules: Create custom validation logic
• Integration Hooks: Connect to external services

API Integration

• Form Data API: Programmatic access to form submissions
• Component API: Dynamically modify form components
• Validation API: Custom server-side validation
• Webhook Support: Real-time form submission notifications

Enterprise Features

• Team Collaboration: Multi-user form editing
• Permission Management: Role-based access control
• Audit Logging: Track all form changes
• White Labeling: Custom branding options

---

This documentation reflects all current features including the smart collapsible settings panel, enhanced grid system with visual previews, intelligent width recommendations, and comprehensive UX improvements implemented in the latest version.

Last updated: December 2024