Clearfield Action Laravel Package

Getting Started

Minimal Steps

1. Installation: Run composer require anish/clearfield-action in your Laravel project.
2. Basic Setup: Add ClearFieldAction::make() to your getHeaderActions() method in either CreateRecord or EditRecord pages.
3. First Use Case: Immediately test the action on a form with multiple fields to reset them to default values with a single click.

Where to Look First

• README: Focus on the "Usage" section for basic and advanced configurations.
• Source Code: Check Actions/ClearFieldAction.php for core logic and available methods.
• Filament Docs: Review Filament’s action system for integration context.

Implementation Patterns

Common Workflows

1. Standard Reset Button:

   ClearFieldAction::make()
       ->label('Reset Form')
       ->icon('heroicon-o-arrow-path')
       ->color('gray');
   

   • Use for forms where users frequently need to clear inputs (e.g., multi-step forms, data entry).

2. Confirmation-Driven Reset:

   ClearFieldAction::make()
       ->requiresConfirmation()
       ->confirmationTitle('Reset All Fields?')
       ->confirmationDescription('This will clear all entered data.')
       ->successNotificationTitle('Form Reset')
       ->successNotificationDescription('All fields have been cleared.');
   

   • Ideal for critical forms (e.g., edit profiles, configurations) where accidental resets could cause data loss.

3. Conditional Reset with Callbacks:

   ClearFieldAction::make()
       ->before(function () {
           // Pre-reset logic (e.g., log event, validate unsaved changes)
           event(new FormResetAttempted());
       })
       ->after(function () {
           // Post-reset logic (e.g., focus first field, reset dependent dropdowns)
           $this->focusField('first_name');
       });
   

   • Use for forms with interdependent fields or custom workflows (e.g., resetting a multi-tab form).

4. Dynamic Labeling:

   ClearFieldAction::make()
       ->label(fn (CreateUser $page) => $page->record ? 'Clear Changes' : 'Reset Form');
   

   • Adapt labels based on context (e.g., "Create" vs. "Edit" pages).

Integration Tips

• Form Complexity: Pair with Filament’s ResetForm for programmatic resets in custom logic.
• Access Control: Use Filament’s action visibility to restrict the action to specific roles:

  ->visible(fn () => auth()->user()->can('manage_users'));
  

• Localization: Translate labels/confirmations via Filament’s localization:

  ->label(__('actions.reset_form'))
  ->confirmationTitle(__('actions.reset_confirm.title'));
  

Gotchas and Tips

Pitfalls

1. Field-Specific Reset Issues:

   • Problem: Custom fields (e.g., RichEditor, FileUpload) may not reset cleanly due to internal state.
   • Fix: Use the after callback to manually reset:

     ->after(function () {
         $this->fillForm([
             'rich_editor_field' => null,
             'file_upload_field' => null,
         ]);
     });
     

2. Confirmation Dialog Overlap:

   • Problem: Multiple actions with requiresConfirmation() may cause UI clutter.
   • Fix: Use unique IDs for dialogs or disable confirmation for non-critical resets.

3. Performance with Large Forms:

   • Problem: Resetting hundreds of fields may cause lag.
   • Fix: Debounce or batch resets using the after callback:

     ->after(function () {
         $this->dispatchBrowserEvent('reset-form-batched');
     });
     

4. Filament Version Mismatch:

   • Problem: Package may not work as expected in Filament v4 vs. v5.
   • Fix: Check the composer.json for version constraints and test in a staging environment.

Debugging

• Logs: Enable Filament’s debug mode (config/filament.php) to log action execution:

  'debug' => env('FILAMENT_DEBUG', false),
  

• Browser Console: Inspect for JavaScript errors if the action fails silently (e.g., confirmation dialog not showing).
• Test Harness: Use Filament’s testing tools to verify action behavior:

  $this->actingAs($user)
       ->get($resource->getCreateRecordRoute())
       ->assertSee('Reset Form');
  

Extension Points

1. Custom Reset Logic:

   • Override the default reset behavior by extending the action:

     use Anish\ClearFieldAction\Actions\ClearFieldAction;
     
     class CustomClearFieldAction extends ClearFieldAction {
         protected function performAction(): void {
             // Custom logic (e.g., soft-reset specific fields)
             $this->fillForm(['field_to_preserve' => 'default_value']);
         }
     }
     

2. Global Configuration:

   • Publish the config file (php artisan vendor:publish --tag="clearfield-action-config") to set defaults:

     'default_confirmation' => false,
     'default_notification' => true,
     

3. Blade Templates:

   • Customize the confirmation dialog or notification by publishing views:

     php artisan vendor:publish --tag="clearfield-action-views"
     

   • Modify resources/views/vendor/clearfield-action/confirmation.blade.php or notification.blade.php.

4. Event Listeners:

   • Listen for reset events to trigger side effects (e.g., analytics, auditing):

     use Anish\ClearFieldAction\Events\FormReset;
     
     FormReset::listen(function (FormReset $event) {
         Log::info('Form reset triggered by user', ['user_id' => auth()->id()]);
     });