Shout Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require awcodes/shout
   

   Ensure you’re using a compatible Filament version (check the compatibility table).

2. Theme Integration: Add the package’s Blade views to your custom theme CSS file (required for styling):

   @source '../../../../vendor/awcodes/shout/resources/**/*.blade.php';
   

   If using Filament Panels, follow Filament’s theme setup guide first.

3. First Use Case: Add a Shout component to a Filament form or infolist:

   use Awcodes\Shout\Shout;
   
   Shout::make('This is a contextual notice!')
       ->icon('heroicon-o-information-circle')
       ->color('info');
   

Implementation Patterns

Common Workflows

1. Form Integration: Use Shout in form sections to guide users:

   Form::section([
       Shout::make('Required fields are marked with an asterisk (*).')
           ->color('warning')
           ->icon('heroicon-o-exclamation-circle'),
   ])->columns(1),
   

2. Infolist Context: Display notices alongside data:

   Infolist::column('status')->badge()
      ->extraAttributes(['class' => 'mb-2'])
      ->afterStateUpdated(function (string $state) {
          return Shout::make('Status updated to: ' . $state)
              ->color('success')
              ->icon('heroicon-o-check-circle');
      }),
   

3. Dynamic Content: Pass variables to Shout for dynamic messages:

   Shout::make("You have {$user->unreadNotifications} unread notifications.")
       ->color('primary')
       ->icon('heroicon-o-bell'),
   

Integration Tips

• Styling: Override default styles via your theme’s CSS. Target .shout-* classes.
• Localization: Use Filament’s __() helper for translatable messages:

  Shout::make(__('This field is required.'))
      ->color('danger')
      ->icon('heroicon-o-x-circle'),
  

• Conditional Rendering: Combine with Laravel logic:

  if ($record->is_archived) {
      Shout::make('This record is archived.')
          ->color('secondary')
          ->icon('heroicon-o-archive');
  }
  

Gotchas and Tips

Pitfalls

1. Missing Theme Setup:

   • Error: Styling fails if @source isn’t added to your CSS.
   • Fix: Verify the path in @source matches your project structure (e.g., ../../../../vendor/ for Laravel).

2. Icon Conflicts:

   • Issue: Heroicons may not load if Filament’s default icons aren’t included.
   • Fix: Ensure your theme includes:

     @source '../../../../vendor/filament/support/resources/views/components/icon.blade.php';
     

3. Blade Context:

   • Gotcha: Shout components must be used within Filament’s Blade context (e.g., forms/infolists). Avoid direct Blade rendering.

Debugging

• Inspect Rendered HTML: Use browser dev tools to check if the Shout component renders. Missing styles often indicate a theme issue.
• Clear Cache: After updating the package or theme:

  php artisan view:clear
  php artisan cache:clear
  

Extension Points

1. Custom Colors: Extend the Shout class to add themes:

   namespace App\Filament\Components;
   
   use Awcodes\Shout\Shout;
   
   class CustomShout extends Shout {
       public static function make(string $message): static {
           return parent::make($message)->color('custom');
       }
   }
   

   Add CSS for .shout-custom.

2. Animation: Use Tailwind’s transition utilities in your theme:

   .shout-enter-active {
       @apply transition-opacity duration-300;
   }
   .shout-enter-from {
       @apply opacity-0;
   }
   

3. Accessibility: Ensure aria-live attributes for dynamic updates:

   Shout::make('Updated!')
       ->extraAttributes(['aria-live' => 'polite'])
       ->color('success'),