Theme Flatly Laravel Package

Getting Started

Minimal Setup

1. Installation Add the theme to your Laravel-based CVEPDB CMS project via Composer:

   composer require cvepdb-cms/theme-flatly
   

   Publish the theme assets (if needed):

   php artisan vendor:publish --tag=flatly-theme-assets
   

2. Enable the Theme Configure the theme in config/cms.php under the themes section:

   'default' => 'flatly',
   'available' => [
       'flatly' => [
           'name' => 'Flatly',
           'path' => 'vendor/cvepdb-cms/theme-flatly',
       ],
   ],
   

3. First Use Case

   • Frontend Rendering: The theme extends CVEPDB’s base layout. Override default views in resources/views/vendor/cvepdb (e.g., resources/views/vendor/cvepdb/layouts/app.blade.php).
   • Asset Integration: Ensure Bootstrap Flatly CSS/JS is loaded via app.blade.php or a service provider:

     @vite(['resources/css/app.css', 'resources/js/app.js']) <!-- If using Vite -->
     <!-- OR -->
     <link href="{{ asset('vendor/flatly/css/bootstrap.min.css') }}" rel="stylesheet">
     

Implementation Patterns

1. View Overrides

• Extend Base Layouts: The theme provides a app.blade.php (or similar) in its resources/views/layouts directory. Override it in your project’s resources/views/vendor/cvepdb/layouts/ to customize:

  @extends('vendor.cvepdb.layouts.app') <!-- Extend theme's layout -->
  @section('title', 'Custom Title')
  

• Component Swapping: Replace theme-specific components (e.g., navigation, cards) by publishing and modifying:

  php artisan vendor:publish --tag=flatly-theme-views
  

2. Dynamic Styling

• SASS Variables: The theme likely uses Bootstrap’s SASS variables. Override them in resources/sass/custom.scss:

  @import 'vendor/flatly/scss/bootstrap';
  $theme-colors: (
    'primary': #3498db,
    'danger': #e74c3c
  );
  

• Theme Switching: Use middleware or a service to toggle themes dynamically:

  // app/Http/Middleware/SwitchTheme.php
  public function handle($request, Closure $next) {
      if ($request->user()->prefers_dark_mode) {
          config(['cms.themes.default' => 'flatly-dark']);
      }
      return $next($request);
  }
  

3. Integration with CVEPDB CMS

• Content Blocks: Leverage CVEPDB’s content management system to inject theme-compatible blocks (e.g., hero sections, feature cards) via the admin panel.
• API-Driven Theming: Fetch theme-specific assets dynamically:

  // Example: Load theme assets via API
  $themeAssets = Theme::find(config('cms.themes.default'))->assets;
  

4. JavaScript Extensions

• Theme-Specific JS: Add scripts to resources/js/flatly.js and include them in app.blade.php:

  @push('scripts')
      <script src="{{ asset('js/flatly.js') }}"></script>
  @endpush
  

• Event Listeners: Extend Flatly’s Bootstrap JS (e.g., modals, tooltips) with custom logic:

  document.addEventListener('DOMContentLoaded', function() {
      // Custom Flatly behavior
      new bootstrap.Modal(document.getElementById('customModal'));
  });
  

Gotchas and Tips

Pitfalls

1. Asset Paths

   • Issue: Hardcoded paths in the theme (e.g., /vendor/flatly/...) may break when publishing assets.
   • Fix: Use Laravel’s mix() or asset() helper:

     <link href="{{ mix('vendor/flatly/css/bootstrap.min.css') }}" rel="stylesheet">
     

2. Theme Conflicts

   • Issue: Overriding views without publishing them first can lead to missing files.
   • Fix: Always publish views before modifying:

     php artisan vendor:publish --tag=flatly-theme-views --force
     

3. Bootstrap Version Mismatch

   • Issue: The theme may depend on a specific Bootstrap version. Conflicts arise if your project uses a different version.
   • Fix: Pin the Bootstrap version in package.json or use a CDN with a specific version.

4. Caching Headaches

   • Issue: Theme changes (CSS/JS) may not reflect due to aggressive caching.
   • Fix: Clear caches:

     php artisan view:clear
     php artisan cache:clear
     npm run dev  # or `npm run build` for production
     

Debugging Tips

• Inspect Published Files: Check storage/framework/views for compiled theme views.
• Browser DevTools: Use the "Elements" tab to verify CSS/JS loads correctly. Look for 404s on theme assets.
• Log Theme Events: Add debug logs in app/Providers/ThemeServiceProvider.php to track theme initialization:

  Log::debug('Active theme:', config('cms.themes.default'));
  

Extension Points

1. Custom Theme Config Extend the theme’s config in config/cms.php:

   'themes' => [
       'flatly' => [
           'custom' => [
               'header_logo' => asset('images/custom-logo.png'),
           ],
       ],
   ],
   

   Access it in views:

   <img src="{{ config('cms.themes.flatly.custom.header_logo') }}" alt="Logo">
   

2. Dynamic Theme Assets Load theme assets conditionally based on user preferences:

   // In a Blade view
   @if (config('cms.themes.default') === 'flatly')
       <link href="{{ asset('vendor/flatly/css/flatly-extensions.css') }}" rel="stylesheet">
   @endif
   

3. Theme-Specific Middleware Restrict access or modify behavior per theme:

   // app/Http/Kernel.php
   'web' => [
       \App\Http\Middleware\FlatlyThemeMiddleware::class,
       // ...
   ],
   

   // app/Http/Middleware/FlatlyThemeMiddleware.php
   public function handle($request, Closure $next) {
       if (config('cms.themes.default') === 'flatly') {
           // Custom logic for Flatly theme
       }
       return $next($request);
   }
   

4. Dark Mode Support If the theme supports dark mode, toggle it via JavaScript or user settings:

   // Toggle dark mode
   document.querySelector('#dark-mode-toggle').addEventListener('click', () => {
       document.body.classList.toggle('dark-mode');
       localStorage.setItem('darkMode', document.body.classList.contains('dark-mode'));
   });