Filament Simple Theme Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require tomatophp/filament-simple-theme
   php artisan filament-simple-theme:install
   npm i && npm run dev
   

2. Register the Plugin: Add the service provider to config/app.php under providers:

   Tomato\FilamentSimpleTheme\FilamentSimpleThemeServiceProvider::class,
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Tomato\FilamentSimpleTheme\FilamentSimpleThemeServiceProvider"
   

3. First Use Case: Apply the theme globally by adding this to your AppServiceProvider or a Filament panel configuration:

   use Tomato\FilamentSimpleTheme\Facades\FilamentSimpleTheme;
   
   public function boot(): void
   {
       FilamentSimpleTheme::enable();
   }
   

   Or enable it for a specific Filament panel:

   Filament::serving(function () {
       FilamentSimpleTheme::enable();
   });
   

Implementation Patterns

Core Workflows

1. Theme Activation:

   • Global Activation: Use FilamentSimpleTheme::enable() in AppServiceProvider or a Filament panel config.
   • Conditional Activation: Enable/disable dynamically based on user roles or preferences:

     Filament::serving(function () {
         if (auth()->user()->isAdmin()) {
             FilamentSimpleTheme::enable();
         }
     });
     

2. Customizing the Sidebar User Menu:

   • Override the default user menu by publishing the views:

     php artisan vendor:publish --tag="filament-simple-theme-views"
     

   • Modify resources/views/vendor/filament-simple-theme/partials/sidebar-user-menu.blade.php to add/remove items (e.g., profile, settings, or custom links).
   • Example customization:

     <div class="space-y-1">
         <x-filament::dropdown-list-item icon="heroicon-o-cog-8-tooth" :label="__('Settings')" />
         <x-filament::dropdown-list-item icon="heroicon-o-arrow-left-on-rectangle" :label="__('Logout')" />
         <!-- Add custom items -->
         <x-filament::dropdown-list-item icon="heroicon-o-bell" :label="__('Notifications')" href="{{ route('notifications.index') }}" />
     </div>
     

3. Dark Mode Integration:

   • The theme supports dark mode out-of-the-box. Ensure your Filament panel’s darkMode config is set:

     Filament::make('AdminPanel', [
         'darkMode' => true,
     ]);
     

   • Override dark mode styles by publishing the assets:

     php artisan vendor:publish --tag="filament-simple-theme-assets"
     

     Then modify resources/css/filament-simple-theme.css.

4. Integration with Filament Panels:

   • Apply the theme to a specific panel by extending the panel configuration:

     Filament::panel(
         Panel::make('admin')
             ->id('admin')
             ->path('admin')
             ->middleware(['auth'])
             ->theme(fn () => FilamentSimpleTheme::enable())
     );
     

5. Localization:

   • Translate the theme’s static strings by publishing the language files:

     php artisan vendor:publish --tag="filament-simple-theme-lang"
     

   • Add translations to resources/lang/{locale}/filament-simple-theme.php.

Integration Tips

• Asset Compilation: Ensure your vite.config.js or webpack.mix.js includes the theme’s assets. The package uses Tailwind CSS, so extend your tailwind.config.js:

  module.exports = {
      presets: [
          require('filament/support/tailwind.config'),
      ],
      // Add theme-specific classes if needed
      theme: {
          extend: {
              colors: {
                  tomato: {
                      50: '#fef7f5',
                      100: '#fde8e3',
                      // ... custom colors
                  },
              },
          },
      },
  };
  

• Custom CSS/JS: Inject custom styles or scripts by hooking into Filament’s assets event:

  Filament::registerViewModel(
      \Tomato\FilamentSimpleTheme\FilamentSimpleTheme::class,
      fn () => null
  )->middleware(function ($view, $model, $operation) {
      $view->with([
          'filamentSimpleThemeScripts' => [
              asset('custom-theme-scripts.js'),
          ],
      ]);
  });
  

• Testing: Test the theme in a staging environment first. Use Filament’s testing helpers to verify the sidebar and user menu render correctly:

  use function Tomato\FilamentSimpleTheme\tests\assertThemeEnabled;
  
  public function test_theme_is_enabled()
  {
      assertThemeEnabled();
  }
  

Gotchas and Tips

Pitfalls

1. Asset Conflicts:

   • If you encounter CSS/JS conflicts, ensure the theme’s assets are compiled after Filament’s core assets. Run npm run dev or npm run build after installing the package.
   • Clear cached assets if issues persist:

     php artisan cache:clear
     npm run dev
     

2. Dark Mode Inconsistencies:

   • Dark mode may not apply consistently if your Filament panel’s darkMode setting conflicts with the theme’s defaults. Explicitly set:

     Filament::make('AdminPanel', [
         'darkMode' => 'class', // or 'media'
     ]);
     

3. Sidebar Width:

   • The sidebar width is fixed by default. To adjust, override the theme’s CSS:

     /* resources/css/filament-simple-theme.css */
     .filament-simple-theme-sidebar {
         width: 280px; /* Adjust as needed */
     }
     

4. User Menu Overrides:

   • If customizing the user menu, ensure you preserve the x-filament::dropdown-list-item components for consistency. Avoid breaking Filament’s dropdown structure.

5. Plugin Registration:

   • Forgetting to register the service provider (FilamentSimpleThemeServiceProvider) will result in the theme not loading. Verify the provider is in config/app.php.

Debugging

1. Theme Not Loading:

   • Check if the theme is enabled by inspecting the page source for the filament-simple-theme class on the <body> tag.
   • Verify the service provider is registered and the enable() method is called.

2. CSS/JS Not Compiled:

   • Run npm run dev and check the browser’s dev tools (Network tab) to ensure the theme’s CSS/JS files are loaded.

3. Blade Views Not Found:

   • If customizing views, ensure they are published to resources/views/vendor/filament-simple-theme/ and the namespace is correct.

4. Dark Mode Not Working:

   • Inspect the <html> tag for the dark class. If missing, ensure your Filament panel’s dark mode setting is correct and the theme’s dark mode toggle is functional.

Tips

1. Extend the Theme:

   • Create a custom theme by copying the package’s assets and views to your project:

     cp -r vendor/tomatophp/filament-simple-theme/resources/views/vendor/filament-simple-theme resources/views/vendor/
     cp -r vendor/tomatophp/filament-simple-theme/resources/css vendor/tomatophp/filament-simple-theme/resources/js resources/
     

   • Then modify them to your liking.

2. Performance:

   • The theme is lightweight. For large applications, consider lazy-loading the sidebar or user menu:

     // resources/js/filament-simple-theme.js
     document.addEventListener('DOMContentLoaded', () => {
         const sidebar = document.querySelector('.filament-simple-theme-sidebar');
         if (sidebar) {
             // Lazy-load logic here
         }
     });
     

3. Accessibility:

   • Ensure the sidebar and user menu are keyboard-navigable. Test with screen readers and adjust ARIA attributes if needed:

     <div class="sidebar" role="navigation" aria-label="Main navigation">
     

4. Version Compatibility:

   • The package is regularly updated. Check the releases for breaking changes when upgrading.

5. Custom Icons:

   • Use Heroicons or custom SVG icons in the user menu. Example:

     <x-filament::dropdown-list-item
         icon="<svg>...</svg>"
         :label="__('Custom Action')"
     />