Filament Advanced Choice Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require codewithdennis/filament-advanced-choice
   

2. Add to Filament Theme: In your custom Filament theme CSS file (e.g., resources/css/filament/filament.css), include:

   @source '../../../../vendor/codewithdennis/filament-advanced-choice/resources/**/*.blade.php';
   

3. Rebuild Assets:

   npm run build
   

   or

   npm run dev
   

First Use Case

Replace a basic Radio or CheckboxList field in a Filament form with a visually enhanced alternative. For example, replace:

Radio::make('status')->options([
    'active' => 'Active',
    'inactive' => 'Inactive',
]),

with:

RadioCard::make('status')
    ->options([
        'active' => 'Active',
        'inactive' => 'Inactive',
    ])
    ->descriptions([
        'active' => 'User is active and can access all features',
        'inactive' => 'User account is suspended',
    ]);

Implementation Patterns

Common Workflows

1. Replacing Basic Fields

• Before: Use Radio or CheckboxList for simple selections.
• After: Use RadioCard, CheckboxCard, etc., for richer UX with descriptions and extras.

  // Basic
  Radio::make('priority')->options([
      'low' => 'Low',
      'medium' => 'Medium',
      'high' => 'High',
  ]);
  
  // Enhanced
  RadioStackedCard::make('priority')
      ->options([
          'low' => 'Low',
          'medium' => 'Medium',
          'high' => 'High',
      ])
      ->descriptions([
          'low' => 'Non-urgent tasks',
          'medium' => 'Moderate urgency',
          'high' => 'Critical tasks',
      ])
      ->extras([
          'low' => 'Due in 7+ days',
          'medium' => 'Due in 3-7 days',
          'high' => 'Due in <3 days',
      ]);
  

2. Leveraging Enums for Type Safety

• Define an enum with HasLabel, HasDescription, and HasExtra interfaces:

  enum TaskPriorityEnum: string implements HasLabel, HasDescription, HasExtra
  {
      case Low;
      case Medium;
      case High;
  
      public function getLabel(): string
      {
          return match ($this) {
              self::Low => 'Low Priority',
              self::Medium => 'Medium Priority',
              self::High => 'High Priority',
          };
      }
  
      public function getDescription(): string
      {
          return match ($this) {
              self::Low => 'Non-urgent tasks',
              self::Medium => 'Moderate urgency',
              self::High => 'Critical tasks',
          };
      }
  
      public function getExtra(): ?string
      {
          return match ($this) {
              self::Low => 'Due in 7+ days',
              self::Medium => 'Due in 3-7 days',
              self::High => 'Due in <3 days',
          };
      }
  }
  

• Use the enum in your field:

  RadioCard::make('priority')->options(TaskPriorityEnum::class);
  

3. Searchable and Bulk-Action Fields

• Add search and bulk toggle to checkbox-based fields:

  CheckboxCard::make('tags')
      ->options([
          'bug' => 'Bug',
          'feature' => 'Feature',
          'documentation' => 'Documentation',
          'enhancement' => 'Enhancement',
      ])
      ->searchable()
      ->bulkToggleable()
      ->searchPrompt('Search tags...')
      ->noSearchResultsMessage('No tags found.');
  

4. Conditional Logic and Dynamic Options

• Disable options dynamically:

  CheckboxList::make('features')
      ->options([
          'notifications' => 'Email Notifications',
          'analytics' => 'Analytics Dashboard',
          'api_access' => 'API Access',
      ])
      ->disableOptionWhen(fn (string $value): bool => $value === 'api_access' && auth()->user()->cannot('access-api'));
  

5. Custom Styling

• Apply custom colors or hide native inputs:

  RadioCard::make('plan')
      ->options(PlanEnum::class)
      ->color(Color::Emerald)
      ->hiddenInputs();
  

Integration Tips

1. Form Validation

• Use standard Filament validation rules (e.g., required, min_items, max_items):

  CheckboxList::make('permissions')
      ->options(PermissionEnum::class)
      ->required()
      ->minItems(1)
      ->maxItems(5);
  

2. Table Columns

• Use the same fields in table columns for consistency:

  Tables\Columns\CheckboxColumn::make('is_active')
      ->label('Status')
      ->trueValue('active')
      ->falseValue('inactive')
      ->options([
          'active' => 'Active',
          'inactive' => 'Inactive',
      ])
      ->color(fn (string $state): string => match ($state) {
          'active' => 'success',
          default => 'danger',
      });
  

3. Reusable Components

• Create a trait or base class for common configurations:

  trait UsesAdvancedChoiceFields
  {
      protected function configureDeliveryTypeField(): RadioStackedCard
      {
          return RadioStackedCard::make('delivery_type')
              ->options(DeliveryTypeEnum::class)
              ->searchable()
              ->bulkToggleable();
      }
  }
  

4. Localization

• Localize labels, descriptions, and extras:

  RadioCard::make('language')
      ->options([
          'en' => __('English'),
          'es' => __('Spanish'),
          'fr' => __('French'),
      ])
      ->descriptions([
          'en' => __('English (US)'),
          'es' => __('Español (Latinoamérica)'),
          'fr' => __('Français'),
      ]);
  

5. Testing

• Test fields in your feature tests:

  $this->get('/admin/resources/tasks/create')
      ->assertSee('RadioCard')
      ->assertSee('High Priority');
  

Gotchas and Tips

Pitfalls

1. Theme CSS Not Applied

• Issue: Fields appear unstyled or broken.
• Fix: Ensure the @source directive is correctly added to your Filament theme CSS file and rebuild assets.

  npm run build
  

2. Enum Not Working as Expected

• Issue: Enum values not displaying correctly or extras not showing.
• Fix: Ensure the enum implements all required interfaces (HasLabel, HasDescription, HasExtra for extras).

  enum MyEnum: string implements HasLabel, HasDescription, HasExtra
  {
      // ...
  }
  

3. Hidden Inputs Not Working

• Issue: Hidden inputs not saving values correctly.
• Fix: Use hiddenInputs() and ensure the field is properly bound in your model/form.

  RadioCard::make('status')
      ->options(StatusEnum::class)
      ->hiddenInputs();
  

4. Search Not Functioning

• Issue: Search input not filtering options.
• Fix: Ensure searchable() is called and the field is properly configured in a form or table.

  CheckboxList::make('tags')->options(TagEnum::class)->searchable();
  

5. Bulk Toggle Not Working

• Issue: Bulk toggle checkbox not appearing or not working.
• Fix: Only works on checkbox-based fields (CheckboxList, CheckboxCard, etc.). Ensure the field is configured correctly.

  CheckboxCard::make('permissions')->options(PermissionEnum::class)->bulkToggleable();
  

6. Repeater Fields Not Working

• Issue: Fields inside repeaters not functioning.
• Fix: Ensure you're using the latest version (v1.0.6+ fixes this issue).

Debugging Tips

1. Inspect Blade Output

• Use browser dev tools to inspect the rendered HTML/Blade templates. Look for missing classes or styles.

2. Check for Conflicting CSS

• If styles are overridden, use !important sparingly or inspect which CSS rule is taking precedence.

3. Enable Debug Mode

• Set APP_DEBUG=true in your .env to see any underlying errors or warnings.

4. Test with Minimal Configuration

• Start with a basic field configuration and gradually add features to isolate issues.

Extension Points

1. Customizing Field Colors

• Override default colors using Filament's Color class:

  RadioCard::make('priority')