# Form Builder Documentation

## Overview

The Form Builder is a powerful drag-and-drop interface for creating dynamic forms. It provides an intuitive, visual way to build forms by selecting components, configuring their properties, and arranging them in your desired layout. Perfect for creating everything from simple contact forms to complex multi-step surveys. Forms can be used independently or integrated with the Process Builder for workflow automation.

> For technical implementation details, please refer to [Form Builder Technical Appendix](FORM_BUILDER_TECHNICAL_APPENDIX.md)

## Getting Started

### Accessing the Form Builder
1. Navigate to `/form-builder` in your browser
2. You'll see a three-panel interface:
   - Left: Component Library
   - Middle: Form Canvas
   - Right: Configuration Panel

### Quick Start Guide
1. **Create a New Form**
   - Click "New Form" in the header
   - Enter a form name and description
   - Start adding components

2. **Add Components**
   - Drag components from the left panel
   - Or click components to add them to the end
   - Components are organized by category for easy finding

3. **Configure Components**
   - Click any component in the canvas to select it
   - Use the right panel to configure its properties
   - Changes are previewed in real-time

4. **Save and Preview**
   - Click "Save" to store your form
   - Use "Preview" to test the form
   - Access saved forms via "Manage Forms"

## Available Components

### Basic Inputs
Perfect for collecting simple text and numeric data:
- **Text Field**: Single line text input
  - Use for: Names, titles, short answers
  - Features: Placeholder text, help text, validation

- **Text Area**: Multi-line text input
  - Use for: Comments, descriptions, long answers
  - Features: Resizable, character count option

- **Number**: Numeric input field
  - Use for: Age, quantity, numeric values
  - Features: Min/max limits, step values

- **Email**: Email address input
  - Use for: Contact forms, user registration
  - Features: Built-in email validation

- **Password**: Secure password input
  - Use for: Login forms, security inputs
  - Features: Password masking, strength indicators

### Selection Inputs
For choosing from predefined options:
- **Select Dropdown**: Single selection menu
  - Use for: Country selection, categories
  - Features: Search, option groups, custom values

- **Checkbox Group**: Multiple choice selection
  - Use for: Multiple selections, preferences
  - Features: Select all, option layout control

- **Radio Group**: Single choice selection
  - Use for: Exclusive choices, yes/no questions
  - Features: Button or traditional style

### Date and Time
Temporal input components:
- **Date Picker**: Date selection
  - Use for: Birthdays, scheduling
  - Features: Date range limits, format options

- **Time Picker**: Time selection
  - Use for: Scheduling, time slots
  - Features: 12/24 hour format, minute steps

- **Date & Time**: Combined selection
  - Use for: Event scheduling, appointments
  - Features: Single field for date and time

### Advanced Components
Specialized input types:
- **File Upload**: File input field
  - Use for: Document upload, image submission
  - Features: File type restrictions, size limits

- **Repeater**: Repeatable field groups
  - Use for: Multiple entries, dynamic lists
  - Features: Add/remove controls, ordering

- **Group**: Field organization
  - Use for: Related fields, form sections
  - Features: Collapsible, conditional display

### Layout Components
Form structure and organization:
- **Heading**: Section titles
  - Use for: Form sections, categories
  - Features: Multiple heading levels

- **Paragraph**: Descriptive text
  - Use for: Instructions, help text
  - Features: Rich text formatting

- **Divider**: Visual separator
  - Use for: Section breaks
  - Features: Various styles

## Form Configuration

### Basic Settings
- Form name and description
- Success/error messages
- Submit button text
- Form layout options

### Validation Options
- Required fields
- Input patterns
- Custom error messages
- Cross-field validation

### Advanced Settings
- Form submission behavior
- Success/failure redirects
- Custom CSS classes
- Event handlers

## Process Builder Integration

The Form Builder integrates with the Process Builder to create workflow-driven forms:

### Connecting Forms to Processes
1. **Create and Save Your Form**
   - Design your form in the Form Builder
   - Save the form with a clear name and description
   - Forms must be saved before they can be used in processes

2. **Using Forms in Process Builder**
   - In Process Builder, add a Form Task to your process
   - Select your form from the Form Selector dropdown
   - The form will be presented to users when they reach this task in the workflow

3. **Form Data in Processes**
   - Data submitted through forms becomes available as process variables
   - Use form data to drive process decisions in gateways
   - Reference form fields in scripts and conditions

### Form URL Parameters
- Forms can accept URL parameters to pre-populate fields
- Process variables can be passed to forms as parameters
- Use the `formId` parameter to load a specific form

## Best Practices

### Form Design
1. Group related fields together
2. Use clear, concise labels
3. Provide help text for complex fields
4. Maintain consistent styling
5. Consider mobile users

### Validation
1. Validate on the appropriate event
2. Provide clear error messages
3. Show validation status clearly
4. Use appropriate validation rules

### User Experience
1. Keep forms as short as possible
2. Use appropriate field types
3. Provide clear instructions
4. Show progress in multi-step forms
5. Ensure keyboard navigation

## Managing Forms

### Saved Forms
- View all forms in the management interface
- Search and filter forms
- Duplicate existing forms
- Archive unused forms

### Form Actions
- Preview: Test the form
- Edit: Modify form structure
- Delete: Remove unused forms
- Export: Save form configuration

### Form Analytics
- View submission statistics
- Track completion rates
- Identify problem fields
- Monitor usage patterns

## Troubleshooting

### Common Issues
1. **Form Not Saving**
   - Check your connection
   - Ensure form has a name
   - Verify all components are valid

2. **Components Not Dragging**
   - Clear browser cache
   - Check for JavaScript errors
   - Ensure proper mouse/touch interaction

3. **Validation Not Working**
   - Verify validation rules syntax
   - Check field names are unique
   - Ensure validation is enabled

4. **Form Not Appearing in Process Builder**
   - Verify the form was saved successfully
   - Check user permissions
   - Refresh the Process Builder page

### Getting Help
- Check the technical documentation
- Contact support team
- Submit bug reports
- Request features

---

For technical details about implementation, component structure, and development guidelines, please refer to the [Technical Appendix](FORM_BUILDER_TECHNICAL_APPENDIX.md).

Last updated: June 10, 2024