159 lines
5.1 KiB
Markdown
159 lines
5.1 KiB
Markdown
# Universal Conditional Field State System
|
|
|
|
This system provides a flexible architecture for implementing conditional field states (readonly, disabled, hidden) based on participant data and interdependent field values.
|
|
|
|
## Architecture Overview
|
|
|
|
The system consists of several key components:
|
|
|
|
1. **FieldConditionInterface** - Defines the contract for condition evaluation
|
|
2. **Concrete Conditions** - Implement specific business logic (age ranges, field values, etc.)
|
|
3. **CompositeCondition** - Combines conditions with AND/OR/NOT logic
|
|
4. **FieldStateProviderInterface** - Manages field state calculation
|
|
5. **ParticipantFieldOptionsProvider** - Enhanced to support state conditions
|
|
6. **Form Integration** - Applied in BookingCreateParticipantType
|
|
|
|
## Usage Examples
|
|
|
|
### Basic Age-Based Condition
|
|
|
|
```php
|
|
// Make a field readonly for participants under 18
|
|
$this->fieldStateConditions['serviceSelection'] = [
|
|
'readonly' => new AgeRangeCondition(null, 17),
|
|
];
|
|
```
|
|
|
|
### Field Dependency Condition
|
|
|
|
```php
|
|
// Disable field if room is not assigned
|
|
$this->fieldStateConditions['mealPreference'] = [
|
|
'disabled' => FieldValueCondition::empty('assignedRoomId'),
|
|
];
|
|
```
|
|
|
|
### Complex Composite Condition
|
|
|
|
```php
|
|
// Hide field for young participants OR if basic service is selected
|
|
$this->fieldStateConditions['advancedOptions'] = [
|
|
'hidden' => CompositeCondition::or(
|
|
new AgeRangeCondition(null, 15),
|
|
FieldValueCondition::equals('serviceType', 'basic')
|
|
),
|
|
];
|
|
```
|
|
|
|
### Multiple State Conditions
|
|
|
|
```php
|
|
// Field with multiple conditional states
|
|
$this->fieldStateConditions['specialServices'] = [
|
|
'readonly' => new AgeRangeCondition(null, 17),
|
|
'required' => FieldValueCondition::equals('roomType', 'premium'),
|
|
'disabled' => CompositeCondition::and(
|
|
FieldValueCondition::empty('assignedRoomId'),
|
|
FieldValueCondition::notEquals('participantType', 'staff')
|
|
),
|
|
];
|
|
```
|
|
|
|
## Available Conditions
|
|
|
|
### AgeRangeCondition
|
|
- `new AgeRangeCondition(18, null)` - At least 18 years old
|
|
- `new AgeRangeCondition(null, 17)` - Under 18 years old
|
|
- `new AgeRangeCondition(18, 65)` - Between 18 and 65 years old
|
|
|
|
### FieldValueCondition
|
|
- `FieldValueCondition::equals('field', 'value')` - Field equals specific value
|
|
- `FieldValueCondition::notEquals('field', 'value')` - Field does not equal value
|
|
- `FieldValueCondition::in('field', ['a', 'b'])` - Field value is in array
|
|
- `FieldValueCondition::empty('field')` - Field is empty or null
|
|
- `FieldValueCondition::isNotEmpty('field')` - Field has a value
|
|
|
|
### CompositeCondition
|
|
- `CompositeCondition::and($cond1, $cond2)` - All conditions must be true
|
|
- `CompositeCondition::or($cond1, $cond2)` - At least one condition must be true
|
|
- `CompositeCondition::not($condition)` - Inverts condition result
|
|
|
|
## State Types
|
|
|
|
- **readonly** - Field is visible but not editable
|
|
- **disabled** - Field interaction is disabled
|
|
- **required** - Field becomes mandatory
|
|
- **hidden** - Field is not displayed (via CSS display: none)
|
|
|
|
## Adding New Conditions
|
|
|
|
To register field state conditions, add them to the `registerFieldStateConditions()` method in `ParticipantFieldOptionsProvider`:
|
|
|
|
```php
|
|
private function registerFieldStateConditions(): void
|
|
{
|
|
// Age-based readonly state
|
|
$this->fieldStateConditions['assignedRoomId'] = [
|
|
'readonly' => new AgeRangeCondition(null, 17),
|
|
];
|
|
|
|
// Field dependency
|
|
$this->fieldStateConditions['mealPreference'] = [
|
|
'disabled' => FieldValueCondition::empty('assignedRoomId'),
|
|
];
|
|
|
|
// Complex business logic
|
|
$this->fieldStateConditions['advancedServices'] = [
|
|
'hidden' => CompositeCondition::or(
|
|
new AgeRangeCondition(null, 15),
|
|
FieldValueCondition::equals('membershipLevel', 'basic')
|
|
),
|
|
'required' => FieldValueCondition::equals('roomType', 'suite'),
|
|
];
|
|
}
|
|
```
|
|
|
|
## Performance Considerations
|
|
|
|
- Conditions use lazy evaluation and short-circuit logic
|
|
- Field state calculations are cached during form processing
|
|
- Dependency tracking prevents unnecessary re-evaluations
|
|
- Bulk state calculation optimizes multiple field updates
|
|
|
|
## Integration with HTMX
|
|
|
|
The system supports real-time field state updates:
|
|
|
|
1. Field changes trigger dependency re-evaluation
|
|
2. State modifications are applied via form rebuilding
|
|
3. HTMX can update field states without full page refresh
|
|
4. Dependency tracking ensures only affected fields are updated
|
|
|
|
## Extending the System
|
|
|
|
### Custom Conditions
|
|
|
|
Create new condition classes implementing `FieldConditionInterface`:
|
|
|
|
```php
|
|
class CustomBusinessRuleCondition implements FieldConditionInterface
|
|
{
|
|
public function evaluate(BookingCreateDto $bookingDto, int $participantIndex, array $formData): bool
|
|
{
|
|
// Custom business logic here
|
|
return true;
|
|
}
|
|
|
|
public function getDependentFields(): array
|
|
{
|
|
return ['fieldThatTriggersThisCondition'];
|
|
}
|
|
|
|
public function getDescription(): string
|
|
{
|
|
return 'Custom business rule description';
|
|
}
|
|
}
|
|
```
|
|
|
|
This system provides a powerful, maintainable foundation for complex conditional field behavior while maintaining clean separation of concerns and extensibility. |