# Concierge Plus Forms System Documentation

The Forms system provides a comprehensive API for building dynamic forms in the Concierge Plus platform. All form logic is handled by the `Forms.php` model located at `lib/packages/core/models/Forms.php`.

## Quick Start

```php
// Initialize form
$this->form_instance = new $this->forms();

// Start form
$this->form_instance->form(array('url' => '/controller/save', 'type' => 'modal_form'));

// Add fields
$this->form_instance->setType("Text")
    ->setLabel("Full Name")
    ->setName("full_name")
    ->setIsRequired(true)
    ->render();

// Add buttons and close
$this->form_instance->buttons($buttons);
$this->form_instance->close_form();
```

## Form Types

### Available Form Types
- `""` (default) - Standard form layout
- `"two_columns"` - Two column layout
- `"modal_form"` - Modal dialog form
- `"labels_above"` - Labels positioned above fields
- `"stacked_form"` - Fully stacked layout

## Field Types

### Basic Input Fields

#### Text
```php
$this->form_instance->setType("Text")
    ->setLabel("Field Label")
    ->setName("field_name")
    ->setValue($value)
    ->setIsRequired(true)
    ->setMaxLength(255)
    ->setPlaceholder("Enter text...")
    ->setClass("custom-class")
    ->render();
```

#### Password
```php
$this->form_instance->setType("Password")
    ->setLabel("Password")
    ->setName("password")
    ->setIsRequired(true)
    ->setIsPasswordVisible(false) // Show/hide toggle
    ->setAllowPaste(false) // Disable paste
    ->render();
```

#### PasswordComplex
Advanced password field with strength validation:
```php
$this->form_instance->setType("PasswordComplex")
    ->setLabel("Password")
    ->setName("password")
    ->setIsRequired(true)
    ->setPlaceholder("Enter a strong password")
    ->render();
```

#### Hidden
```php
$this->form_instance->setType("Hidden")
    ->setName("id")
    ->setValue($id)
    ->render();
```

#### Textarea
```php
$this->form_instance->setType("Textarea")
    ->setLabel("Description")
    ->setName("description")
    ->setValue($value)
    ->setWidth("100%")
    ->setHeight("200px")
    ->setMaxLength(1000)
    ->render();
```

### Rich Text Fields

#### RichText
Modern rich text editor:
```php
$this->form_instance->setType("RichText")
    ->setLabel("Content")
    ->setName("content")
    ->setValue($content)
    ->setHeight("300px")
    ->render();
```

#### RichTextLegacy
Legacy TinyMCE editor:
```php
$this->form_instance->setType("RichTextLegacy")
    ->setLabel("Content")
    ->setName("content")
    ->setValue($content)
    ->setTinymceBasicControl(true)
    ->setTinymceTagsControl(false)
    ->render();
```

### Numeric Fields

#### Number
```php
$this->form_instance->setType("Number")
    ->setLabel("Quantity")
    ->setName("quantity")
    ->setValue($value)
    ->setDigits(3) // Max digits
    ->render();
```

#### Currency
```php
$this->form_instance->setType("Currency")
    ->setLabel("Amount")
    ->setName("amount")
    ->setValue($value)
    ->setDecimalPlaces(2)
    ->render();
```

#### Percent
```php
$this->form_instance->setType("Percent")
    ->setLabel("Percentage")
    ->setName("percentage")
    ->setValue($value)
    ->render();
```

### Date and Time Fields

#### Date
```php
$this->form_instance->setType("Date")
    ->setLabel("Date")
    ->setName("event_date")
    ->setValue($date)
    ->setDateRestriction("today") // "past", "future", "today"
    ->setDateFormat("Y-m-d")
    ->render();
```

#### Time
```php
$this->form_instance->setType("Time")
    ->setLabel("Time")
    ->setName("event_time")
    ->setValue($time)
    ->setMinuteSteps(15) // 15-minute intervals
    ->render();
```

#### Time to Time
```php
$this->form_instance->setType("Time to Time")
    ->setLabel("Time Range")
    ->setName("time_range")
    ->setValue($time_range)
    ->render();
```

#### Date and Time
```php
$this->form_instance->setType("Date and Time")
    ->setLabel("Event DateTime")
    ->setName("event_datetime")
    ->setValue($datetime)
    ->render();
```

#### Date Interval
```php
$this->form_instance->setType("Date Interval")
    ->setLabel("Date Range")
    ->setName("date_range")
    ->setValue($date_range)
    ->render();
```

### Selection Fields

#### Dropdown
```php
$options = array(
    '1' => 'Option 1',
    '2' => 'Option 2',
    '3' => 'Option 3'
);

$this->form_instance->setType("Dropdown")
    ->setLabel("Select Option")
    ->setName("option")
    ->setOptions($options)
    ->setValue($selected_value)
    ->setHasBlankOption(true)
    ->setHasBlankOptionDescription("Please select...")
    ->render();
```

#### Multiple Options
Multi-select dropdown:
```php
$this->form_instance->setType("Multiple Options")
    ->setLabel("Select Multiple")
    ->setName("options")
    ->setOptions($options)
    ->setValue($selected_array)
    ->setHasSearch(true) // Enable search
    ->render();
```

#### Multiple Options Dropdown
```php
$this->form_instance->setType("Multiple Options Dropdown")
    ->setLabel("Select Multiple")
    ->setName("options")
    ->setOptions($options)
    ->setValue($selected_array)
    ->render();
```

#### MultipleRadios
```php
$this->form_instance->setType("MultipleRadios")
    ->setLabel("Choose Option")
    ->setName("radio_option")
    ->setOptions($options)
    ->setValue($selected_value)
    ->setIsRequired(true)
    ->render();
```

#### Yes or No
```php
$this->form_instance->setType("Yes or No")
    ->setLabel("Approve Request?")
    ->setName("approved")
    ->setValue($value) // 1 or 0
    ->render();
```

#### RadioBox
```php
$this->form_instance->setType("RadioBox")
    ->setLabel("Radio Options")
    ->setName("radio_choice")
    ->setOptions($options)
    ->setValue($selected_value)
    ->render();
```

### Checkbox Fields

#### Checkbox
Single checkbox:
```php
$this->form_instance->setType("Checkbox")
    ->setLabel("I agree to terms")
    ->setName("agree_terms")
    ->setValue(1) // Checked value
    ->setIsRequired(true)
    ->render();
```

#### Checkboxes
Multiple checkboxes:
```php
$this->form_instance->setType("Checkboxes")
    ->setLabel("Select Options")
    ->setName("checkbox_options")
    ->setOptions($options)
    ->setValue($selected_array)
    ->render();
```

### Advanced Fields

#### Groups / GroupsV3
Group selector for audience targeting:
```php
$this->form_instance->setType("GroupsV3")
    ->setName("groups")
    ->setLabel("Audience")
    ->setText("Select target audience")
    ->setHideUnitGroups(false)
    ->setAlwaysSelectPropertyManager(true)
    ->setValue($selected_groups)
    ->setIsRequired(true)
    ->render();
```

#### Search
User search field:
```php
$this->form_instance->setType("Search")
    ->setLabel("Search Users")
    ->setName("user_search")
    ->setColumns($columns) // Search columns
    ->setUsers("Multiple") // "Single" or "Multiple"
    ->setShowAllUsers(true)
    ->render();
```

#### UserSearch
```php
$this->form_instance->setType("UserSearch")
    ->setLabel("Select User")
    ->setName("user_id")
    ->setValue($user_id)
    ->render();
```

#### UnitSearch
```php
$this->form_instance->setType("UnitSearch")
    ->setLabel("Select Unit")
    ->setName("unit_id")
    ->setValue($unit_id)
    ->render();
```

#### Phone / Phone Number
```php
$this->form_instance->setType("Phone")
    ->setLabel("Phone Number")
    ->setName("phone")
    ->setValue($phone)
    ->setCCProtection(true) // Country code protection
    ->render();
```

#### MapSearch
```php
$this->form_instance->setType("MapSearch")
    ->setLabel("Location")
    ->setName("location")
    ->setValue($location)
    ->render();
```

#### ColorWheel
```php
$this->form_instance->setType("ColorWheel")
    ->setLabel("Pick Color")
    ->setName("color")
    ->setValue($color) // Hex color
    ->render();
```

#### IconDropdown
```php
$this->form_instance->setType("IconDropdown")
    ->setLabel("Select Icon")
    ->setName("icon")
    ->setValue($icon)
    ->render();
```

#### Slider
```php
$this->form_instance->setType("Slider")
    ->setLabel("Rating")
    ->setName("rating")
    ->setValue($rating)
    ->render();
```

#### FilePicker
```php
$this->form_instance->setType("FilePicker")
    ->setLabel("Upload File")
    ->setName("file")
    ->render();
```

#### Attachments
```php
$this->form_instance->setType("Attachments")
    ->setLabel("Attachments")
    ->setName("attachments")
    ->setIdObject($id_object)
    ->render();
```

#### Signature
```php
$this->form_instance->setType("Signature")
    ->setLabel("Signature")
    ->setName("signature")
    ->render();
```

### Custom Fields

#### Custom
Renders custom control from views:
```php
$this->form_instance->setType("Custom")
    ->setControlPath('controls/')
    ->setControl("custom_field_name")
    ->render();
```

#### CustomWithSkeleton
```php
$this->form_instance->setType("CustomWithSkeleton")
    ->setHTML($custom_html)
    ->render();
```

### Utility Fields

#### Separator
```php
$this->form_instance->setType("Separator")
    ->render();
```

#### Terms & Conditions
```php
$this->form_instance->setType("Terms & Conditions")
    ->setLabel("Terms and Conditions")
    ->setName("terms")
    ->render();
```

#### ToggleSwitch
```php
$this->form_instance->setType("ToggleSwitch")
    ->setLabel("Enable Feature")
    ->setName("enabled")
    ->setValue($enabled)
    ->render();
```

#### Recaptcha
```php
$this->form_instance->setType("Recaptcha")
    ->setName("recaptcha")
    ->render();
```

## Common Methods

### Required Methods
- `setType($type)` - Set field type
- `setName($name)` - Set field name attribute
- `render()` - Render the field

### Common Setters
- `setLabel($label)` - Field label
- `setValue($value)` - Default/current value
- `setPlaceholder($text)` - Placeholder text
- `setClass($class)` - CSS classes
- `setWidth($width)` - Field width
- `setHeight($height)` - Field height
- `setIsRequired($bool)` - Required validation
- `setIsReadonly($bool)` - Read-only state
- `setIsDisabled($bool)` - Disabled state
- `setIsVisible($bool)` - Visibility
- `setMaxLength($int)` - Maximum length
- `setTooltip($text)` - Help tooltip

### Options Methods
- `setOptions($array)` - Set dropdown/select options
- `setHasBlankOption($bool)` - Add blank option
- `setHasBlankOptionDescription($text)` - Blank option text
- `setKeyProperty($prop)` - Object key property
- `setKeyDescription($prop)` - Object description property

### Date/Time Methods
- `setDateRestriction($type)` - "past", "future", "today"
- `setDateFormat($format)` - Date format string
- `setMinuteSteps($minutes)` - Time picker intervals

### Advanced Methods
- `setAppend($html)` - Append HTML after field
- `setIgnoreSkeleton($bool)` - Skip form skeleton
- `setContainerWidth($width)` - Container width override
- `setLabelWidth($width)` - Label width override

## Form Structure Methods

### Form Initialization
```php
// Start form
$this->form_instance->form(array(
    'url' => '/controller/action',
    'type' => 'modal_form',
    'class' => 'custom-form',
    'method' => 'POST'
));
```

### Form Buttons
```php
$buttons = array(
    'cancel' => array('url' => '/cancel-url'),
    'save' => array('text' => 'Save Changes'),
    'submit' => array('text' => 'Submit', 'class' => 'btn-primary')
);

$this->form_instance->buttons($buttons);
```

### Close Form
```php
$this->form_instance->close_form();
```

## Usage Examples

### Basic Contact Form
```php
$this->form_instance->form(array('url' => '/contact/save', 'type' => 'two_columns'));

$this->form_instance->setType("Text")
    ->setLabel("Full Name")
    ->setName("name")
    ->setIsRequired(true)
    ->render();

$this->form_instance->setType("Text")
    ->setLabel("Email")
    ->setName("email")
    ->setIsRequired(true)
    ->render();

$this->form_instance->setType("Phone")
    ->setLabel("Phone Number")
    ->setName("phone")
    ->render();

$this->form_instance->setType("Textarea")
    ->setLabel("Message")
    ->setName("message")
    ->setIsRequired(true)
    ->setHeight("150px")
    ->render();

$buttons = array(
    'cancel' => array('url' => '/contact'),
    'submit' => array('text' => 'Send Message')
);

$this->form_instance->buttons($buttons);
$this->form_instance->close_form();
```

### Event Registration Form
```php
$this->form_instance->form(array('url' => '/events/register', 'type' => 'modal_form'));

$this->form_instance->setType("Hidden")
    ->setName("event_id")
    ->setValue($event->id)
    ->render();

$this->form_instance->setType("Text")
    ->setLabel("Attendee Name")
    ->setName("attendee_name")
    ->setIsRequired(true)
    ->render();

$this->form_instance->setType("Number")
    ->setLabel("Number of Guests")
    ->setName("guest_count")
    ->setValue(0)
    ->setDigits(2)
    ->render();

$dietary_options = array(
    'none' => 'No restrictions',
    'vegetarian' => 'Vegetarian',
    'vegan' => 'Vegan',
    'gluten_free' => 'Gluten-free'
);

$this->form_instance->setType("MultipleRadios")
    ->setLabel("Dietary Restrictions")
    ->setName("dietary")
    ->setOptions($dietary_options)
    ->setValue('none')
    ->render();

$this->form_instance->setType("Textarea")
    ->setLabel("Special Requests")
    ->setName("notes")
    ->setPlaceholder("Any special accommodations needed...")
    ->render();

$buttons = array(
    'cancel' => array('url' => '/events'),
    'submit' => array('text' => 'Register', 'class' => 'btn-success')
);

$this->form_instance->buttons($buttons);
$this->form_instance->close_form();
```

### Poll Creation Form (Multiple Questions)
```php
$this->form_instance->form(array('url' => '/polls/savePoll', 'class' => 'add-form'));

$this->form_instance->setType("Text")
    ->setLabel("Poll Title")
    ->setName("title")
    ->setValue($poll->title)
    ->setIsRequired(true)
    ->render();

$this->form_instance->setType("GroupsV3")
    ->setName("groups")
    ->setLabel("Audience")
    ->setAlwaysSelectPropertyManager(true)
    ->setValue($selected_groups)
    ->setIsRequired(true)
    ->render();

$this->form_instance->setType("Date")
    ->setLabel("Expiration Date")
    ->setName("poll_expire_at")
    ->setDateRestriction("today")
    ->render();

$voting_options = array(
    '1' => 'Single Choice',
    '2' => 'Multiple Choice'
);

$this->form_instance->setType("MultipleRadios")
    ->setLabel("Voting System")
    ->setName("voting_system")
    ->setOptions($voting_options)
    ->setValue(2)
    ->setIsRequired(true)
    ->render();

// Custom control for multiple questions
$this->form_instance->setType("Custom")
    ->setControlPath('controls/')
    ->setControl("poll_questions")
    ->render();

$buttons = array(
    'cancel' => array('url' => '/polls'),
    'save_draft' => array('text' => 'Save Draft'),
    'publish' => array('text' => 'Publish Poll', 'class' => 'btn-success')
);

$this->form_instance->buttons($buttons);
$this->form_instance->close_form();
```

## Best Practices

### 1. Field Naming
- Use descriptive names: `full_name` instead of `name`
- Follow snake_case convention
- Use consistent prefixes for related fields

### 2. Validation
- Always set `setIsRequired(true)` for mandatory fields
- Use appropriate field types for automatic validation
- Set reasonable `setMaxLength()` values

### 3. User Experience
- Provide clear labels and placeholders
- Use help text and tooltips for complex fields
- Group related fields logically

### 4. Accessibility
- Always provide labels for screen readers
- Use semantic field types
- Ensure proper tab order

### 5. Performance
- Only load necessary assets using `Asset_manager`
- Use appropriate form types for the context
- Minimize custom controls when standard fields suffice

## Form Validation

The Forms system integrates with jQuery Validation. Add validation rules in your JavaScript:

```javascript
$('.add-form').validate({
    rules: {
        field_name: {
            required: true,
            minlength: 3,
            maxlength: 50
        },
        email: {
            required: true,
            email: true
        }
    },
    messages: {
        field_name: {
            required: "This field is required",
            minlength: "Minimum 3 characters required"
        }
    }
});
```

## Asset Loading

Load required JavaScript libraries in your controller:

```php
$this->Asset_manager->loadLib(array(
    'ui',           // Core UI components
    'validation',   // Form validation
    'bootstrap',    // Bootstrap components
    'datatable',    // DataTables
    'modals'        // Modal dialogs
));
```

This comprehensive documentation covers all field types and common usage patterns in the Concierge Plus Forms system.