Awrel Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require khoirulaksara/awrel
   

   Publish the package assets and config:

   php artisan vendor:publish --provider="Khoirulaksara\Awrel\AwrelServiceProvider" --tag="awrel-config"
   php artisan vendor:publish --provider="Khoirulaksara\Awrel\AwrelServiceProvider" --tag="awrel-assets"
   

2. Enable the Plugin Register the plugin in app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \Khoirulaksara\Awrel\AwrelPlugin::make(),
           ]);
   }
   

3. First Use Case Customize the login page by modifying .env:

   AWREL_LOGIN_LAYOUT=modern
   AWREL_LOGIN_BACKGROUND_COLOR=#1a202c
   AWREL_LOGIN_BACKGROUND_IMAGE=/images/custom-bg.jpg
   

   Then, in config/awrel.php, adjust other settings like branding, layout_variant, and glassmorphism.

Implementation Patterns

Core Workflows

1. Branding & Layout

   • Use AwrelServiceProvider to override default assets (logo, favicon) via public_path() overrides.
   • Toggle layouts dynamically in a Filament setting panel:

     use Khoirulaksara\Awrel\Facades\Awrel;
     
     Awrel::setLayoutVariant('sidebar'); // or 'horizontal'
     Awrel::enableBoxedLayout(true);
     

2. Skeleton Loaders Integrate with Filament tables using deferLoading():

   use Khoirulaksara\Awrel\Facades\Awrel;
   
   public static function table(Table $table): Table
   {
       return $table
           ->deferLoading() // Auto-generates skeleton loaders
           ->columns([
               // columns...
           ]);
   }
   

3. Sticky Table Actions Enable for specific tables:

   public static function table(Table $table): Table
   {
       return $table
           ->stickyActions() // Pins actions column on scroll
           ->columns([
               // columns...
           ]);
   }
   

4. Dynamic Theming Extend the color palette via config/awrel.php:

   'colors' => [
       'primary' => '#3b82f6',
       'secondary' => '#10b981',
       'glass' => [
           'opacity' => 0.7,
           'backdrop' => 'rgba(0, 0, 0, 0.1)',
       ],
   ],
   

Integration Tips

• Filament Widgets: Use Awrel::decorateWidget() to apply glassmorphism or skeleton effects:

  public static function widget(Widget $widget): Widget
  {
      return $widget
          ->decorate(Awrel::glassmorphism()) // Applies frosted-glass effect
          ->view('custom-widget');
  }
  

• Livewire Components: Leverage the loading bar by extending AwrelLivewire:

  use Khoirulaksara\Awrel\Livewire\AwrelLivewire;
  
  class MyComponent extends AwrelLivewire
  {
      // Component logic...
  }
  

• Custom Animations: Override CSS in resources/css/awrel/custom.css:

  @keyframes awrel-notification-ring {
      0% { transform: scale(0.95); opacity: 0; }
      100% { transform: scale(1); opacity: 1; }
  }
  

Gotchas and Tips

Pitfalls

1. Asset Conflicts

   • Ensure public_path() overrides in config/awrel.php point to correct paths:

     'paths' => [
         'logo' => public_path('images/custom-logo.svg'),
         'favicon' => public_path('images/custom-favicon.ico'),
     ],
     

   • Clear cached views after asset changes:

     php artisan view:clear
     

2. Layout Variant Mismatches

   • Horizontal layouts may require additional padding/margin adjustments in CSS:

     .awrel-horizontal .filament-main-canvas {
         padding-top: 80px !important;
     }
     

   • Test boxedLayout on mobile; may need responsive tweaks.

3. Skeleton Loader Timing

   • deferLoading() relies on Filament’s lazy-loading. For immediate skeletons, manually add:

     @if (request()->wantsJson())
         <div class="awrel-skeleton"></div>
     @endif
     

4. Glassmorphism Performance

   • Disable on low-end devices by checking config/awrel.php:

     'glassmorphism' => [
         'enabled' => env('AWREL_GLASS_ENABLED', true),
         'exclude_devices' => ['mobile'], // Add 'mobile' to disable on mobiles
     ],
     

Debugging

• Disabled Features: Check config/awrel.php for false values or environment overrides.
• CSS Overrides: Use browser dev tools to inspect !important conflicts with Filament’s default styles.
• Livewire Loading Bar: Ensure AwrelLivewire is extended and appends are configured in config/livewire.php:

  'append_script_tag' => true,
  

Extension Points

1. Custom Animations Extend the AwrelServiceProvider to register new animations:

   public function boot()
   {
       Awrel::extendAnimations([
           'pulse' => '@keyframes pulse { ... }',
       ]);
   }
   

2. Dynamic Theming via API Fetch theme preferences from a database and apply them runtime:

   use Khoirulaksara\Awrel\Facades\Awrel;
   
   public function mount()
   {
       $theme = Theme::find($this->themeId);
       Awrel::setColors($theme->colors);
       Awrel::setLayoutVariant($theme->layout);
   }
   

3. Dark Mode Support Override config/awrel.php for dark mode:

   'dark_mode' => [
       'enabled' => true,
       'glass_opacity' => 0.9,
   ],
   

   Then use Filament’s dark mode toggle:

   use Filament\Panel;
   
   public function panel(Panel $panel): Panel
   {
       return $panel
           ->darkMode();
   }
   

4. Localization Translate strings via resources/lang/vendor/awrel:

   'login' => [
       'title' => 'Custom Login Title',
   ],