Lara Demo Theme Laravel Package

Getting Started

Minimal Steps to First Use

1. Prerequisites:

   • Install Lara CMS (v8.x+) as the parent system.
   • Ensure Laravel 8+ is running (tested with Laravel 11 in v8.5.1).
   • Verify PHP 8.1+ and Composer are installed.

2. Install the Demo Theme:

   composer require appdezign/lara-demo-theme
   

   • Publish the theme assets (if needed):

     php artisan vendor:publish --tag=lara-demo-theme-assets
     

3. Configure Lara CMS:

   • Update config/lara-cms.php to include the demo theme in the themes array:

     'themes' => [
         'demo' => [
             'name' => 'Demo Theme',
             'path' => base_path('vendor/appdezign/lara-demo-theme'),
             'is_child' => true,
             'parent' => 'base', // Assumes 'base' theme exists
         ],
     ],
     

4. First Use Case:

   • Access the demo theme in the Lara CMS admin panel (/admin).
   • Create a new page using the demo theme’s templates (e.g., home.blade.php).
   • Preview the page at /demo-theme (or your configured route).

5. Key Files to Inspect:

   • resources/views/ – Blade templates for pages/components.
   • config/demo-theme.php – Theme-specific settings (if published).
   • routes/web.php – Theme routes (may override Lara CMS defaults).

Implementation Patterns

Usage Patterns

1. Theme Inheritance Workflow

• Extend the Base Theme: Override parent templates by copying files from vendor/appdezign/lara-demo-theme/resources/views/ to your project’s resources/views/ (e.g., resources/views/partials/header.blade.php).
• Use @extends in Blade: Leverage the parent theme’s layouts:

  @extends('demo-theme::layouts.app')
  @section('content')
      {{ $slot }}
  @endsection
  

• Dynamic Theme Switching: Configure Lara CMS to switch themes via config/lara-cms.php:

  'active_theme' => env('THEME', 'demo'),
  

2. Content Management Integration

• Create CMS Blocks: Use Lara CMS’s block system to add dynamic content:

  @foreach($page->blocks as $block)
      @includeIf("demo-theme::blocks.{$block->type}", ['block' => $block])
  @endforeach
  

• Custom Block Types: Register new block types in AppServiceProvider:

  public function boot()
  {
      LaraCms::blocks()->register('custom_block', \App\Blocks\CustomBlock::class);
  }
  

3. Routing and Controllers

• Theme-Specific Routes: Define routes in routes/web.php:

  Route::prefix('demo')->group(function () {
      Route::get('/', [\Appdezign\DemoTheme\Http\Controllers\PageController::class, 'home']);
  });
  

• Controller Inheritance: Extend Lara CMS controllers:

  namespace App\Http\Controllers;
  use Appdezign\DemoTheme\Http\Controllers\DemoThemeController;
  
  class CustomDemoController extends DemoThemeController
  {
      public function customPage() { ... }
  }
  

4. Asset Management

• Publish Assets: Customize CSS/JS by publishing assets:

  php artisan vendor:publish --tag=lara-demo-theme-assets --force
  

• Versioned Assets: Use Laravel Mix/Vite to compile theme assets:

  // resources/js/demo-theme.js
  require('./demo-theme');
  

  // webpack.mix.js
  mix.js('resources/js/demo-theme.js', 'public/js')
       .postCss('resources/css/demo-theme.css', 'public/css', []);
  

5. Localization and Translations

• Theme Translations: Add language files to resources/lang/:

  // resources/lang/en/demo-theme.php
  return [
      'welcome' => 'Welcome to our Demo Theme!',
  ];
  

• Fallback to Parent: Use @lang('demo-theme::key', 'fallback') in Blade.

Workflows

A. Rapid Prototyping

1. Clone the Demo Theme:

   composer create-project appdezign/lara-demo-theme my-demo-site
   

2. Seed Sample Content:

   php artisan laracms:seed --theme=demo
   

3. Iterate with Live Preview:
   • Use Lara CMS’s live preview mode (?preview=true) to test changes without caching issues.

B. Customizing for Production

1. Fork the Theme:
   • Move the theme to resources/themes/demo and update config/lara-cms.php:

     'themes' => [
         'demo' => [
             'path' => resource_path('themes/demo'),
         ],
     ],
     

2. Override Templates:
   • Copy vendor/appdezign/lara-demo-theme/resources/views/ to resources/themes/demo/views/.
3. Extend Functionality:
   • Add custom directives, middleware, or service providers in AppServiceProvider.

C. Multi-Environment Theming

• Use environment-specific theme configurations:

  // config/lara-cms.php
  'active_theme' => env('THEME', 'demo'),
  

  • Set THEME=demo in .env for development, THEME=custom for production.

Integration Tips

1. Laravel Ecosystem

• Leverage Existing Packages:
  • Integrate with Laravel Scout for search:

    use Laravel\Scout\Searchable;
    class Page extends Model implements Searchable { ... }
    

  • Use Laravel Nova for admin customization (if needed).

2. Frontend Tools

• Tailwind CSS: Extend the demo theme’s Tailwind config:

  // tailwind.config.js
  module.exports = {
      presets: [require('appdezign/lara-demo-theme/tailwind.config')],
      theme: {
          extend: {
              colors: {
                  primary: '#10B981', // Override demo theme colors
              },
          },
      },
  };
  

• Alpine.js: Use Alpine for interactive elements without heavy JS:

  <button x-on:click="toggleMobileMenu()" class="mobile-menu-button">
      Menu
  </button>
  

3. Database and Media

• Media Library: Use Lara CMS’s media manager or integrate Spatie Media Library:

  use Spatie\MediaLibrary\HasMedia;
  class Page extends Model implements HasMedia { ... }
  

• Custom Fields: Extend Lara CMS’s field system:

  LaraCms::fields()->register('rich_text', \App\Fields\RichTextField::class);
  

4. API and Headless CMS

• Expose CMS Content via API:

  Route::middleware('auth:sanctum')->get('/api/pages', [PageController::class, 'index']);
  

• Use Inertia.js for SPA-like experiences:

  <div x-data="{ page: @entangle('page') }">
      {{ $page->title }}
  </div>
  

Gotchas and Tips

Pitfalls

1. Theme Inheritance Issues

• Problem: Overriding parent templates may break if the parent theme’s structure changes.
  • Fix: Document all overrides and test after Lara CMS updates.
• Problem: Child themes may not inherit all parent theme assets (CSS/JS).
  • Fix: Manually publish and merge assets:

    php artisan vendor:publish --tag=lara-demo-theme-assets --force
    

2. Route Conflicts

• Problem: Demo theme routes may clash with existing Laravel routes.
  • Fix: Use route namespaces or middleware:

    Route::prefix('demo')->middleware(['web', 'demo-theme'])->group(...);
    

3. Caching Quirks

• Problem: Lara CMS caches routes/views aggressively, causing stale content.
  • Fix: Clear caches explicitly:

    php artisan view:clear
    php artisan route:clear
    php artisan cache:clear
    

  • Tip: Use ?preview=true in development to bypass caching.

4. Laravel 11+ Compatibility

• Problem: Directory structure changes (e.g., app/ moved to app/ root) may break paths.
  • Fix: Update composer.json aliases and Blade @include paths:

    @include('demo-theme::partials.header')  // Use vendor path
    

5. Database Schema Mismatches

• Problem: Lara