Lara Pro Base Theme Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation:

   composer require appdezign/lara-pro-base-theme
   php artisan vendor:publish --tag=lara-pro-base-theme-config
   php artisan vendor:publish --tag=lara-pro-base-theme-assets
   php artisan vendor:publish --tag=lara-pro-base-theme-views
   

   • Publish config, assets, and views to your project.

2. Configuration:

   • Update config/theme.php with your site name, logo, and other global settings.
   • Configure CMS-related settings (e.g., default page templates, media paths).

3. First Page Creation:

   • Use the built-in Filament admin panel (if enabled) or create a Page model record via Tinker:

     php artisan tinker
     >>> $page = \App\Models\Page::create([
     ...     'title' => 'Home',
     ...     'slug' => 'home',
     ...     'template' => 'default',
     ...     'content' => '<h1>Welcome to our site!</h1>'
     ... ]);
     

4. Routing:

   • Ensure your routes use the theme’s middleware:

     Route::middleware(['web', 'theme'])->group(function () {
         Route::get('/', [\Appdezign\LaraProBaseTheme\Http\Controllers\PageController::class, 'show']);
     });
     

5. View Rendering:

   • Access the page via a Blade template:

     @extends('lara-pro-base-theme::layouts.master')
     @section('content')
         @include('lara-pro-base-theme::pages.default', ['page' => $page])
     @endsection
     

Where to Look First

• Documentation: Start with LaraCMS Docs for theme-specific guides.
• Published Files:
  • config/theme.php: Global theme settings.
  • resources/views/vendor/lara-pro-base-theme/: Override or extend theme views.
  • public/vendor/lara-pro-base-theme/: Theme assets (CSS/JS).
• Service Provider: Check app/Providers/ThemeServiceProvider.php for bindings and extensions.

First Use Case: Static Homepage

1. Publish the theme assets and views.
2. Create a Page record for your homepage (e.g., slug home).
3. Extend the default template (resources/views/vendor/lara-pro-base-theme/pages/default.blade.php) to add custom sections.
4. Route the homepage to the PageController:

   Route::get('/', [\Appdezign\LaraProBaseTheme\Http\Controllers\PageController::class, 'show'])->name('home');
   

5. Visit / to see your homepage rendered with the theme.

Implementation Patterns

Core Workflows

1. Template Inheritance and Overrides

• Pattern: Use the theme’s Blade template hierarchy to extend or replace sections.

  • Base Layout: resources/views/vendor/lara-pro-base-theme/layouts/master.blade.php
  • Page Templates: resources/views/vendor/lara-pro-base-theme/pages/{template}.blade.php
  • Partials: resources/views/vendor/lara-pro-base-theme/partials/{partial}.blade.php

  Example: Override the header partial:

  <!-- resources/views/vendor/lara-pro-base-theme/partials/header.blade.php -->
  @extends('lara-pro-base-theme::partials.header')
  @section('header')
      <div class="custom-header">
          @include('lara-pro-base-theme::partials.header.default')
      </div>
  @endsection
  

2. Dynamic Content Blocks

• Pattern: Use the ContentBlock model to create reusable components.
  • Define blocks in the admin panel (Filament) or via migrations.
  • Render blocks in templates:

    @foreach($page->contentBlocks as $block)
        @include('lara-pro-base-theme::blocks.'.$block->type, ['block' => $block])
    @endforeach
    

3. Asset Management

• Pattern: Leverage Laravel Mix/Vite to compile theme assets.
  • CSS: Combine theme styles with your app’s CSS:

    // webpack.mix.js
    mix.postCss('resources/css/app.css', 'public/css', [
        require('tailwindcss'),
    ]);
    mix.sass('resources/scss/lara-pro-base-theme.scss', 'public/css');
    

  • JS: Use Alpine.js or Livewire for interactivity:

    @livewire('theme-component')
    

4. Admin Integration (Filament)

• Pattern: Extend the Filament admin panel for CMS management.
  • Customize resources:

    // app/Filament/Resources/PageResource.php
    public static function form(Form $form): Form
    {
        return $form
            ->schema([
                TextInput::make('title')->required(),
                Select::make('template')->options(['default', 'blog', 'custom']),
                // ...
            ]);
    }
    

5. Middleware and Routing

• Pattern: Protect routes and customize middleware.
  • Register theme middleware in app/Http/Kernel.php:

    protected $routeMiddleware = [
        'theme' => \Appdezign\LaraProBaseTheme\Http\Middleware\ThemeMiddleware::class,
    ];
    

  • Route CMS pages dynamically:

    Route::get('/{slug}', [PageController::class, 'show'])
        ->name('page.show')
        ->middleware(['web', 'theme']);
    

Integration Tips

Laravel Ecosystem

• Livewire: Use Livewire components for dynamic sections:

  @livewire('theme-hero-section', ['page' => $page])
  

• Filament: Extend Filament panels for custom admin features:

  Filament::serving(function () {
      ThemeServiceProvider::make();
  });
  

• Scout: Integrate search with Laravel Scout:

  use Appdezign\LaraProBaseTheme\Models\Page;
  Page::addGlobalScope(new \Laravel\Scout\Builder);
  

Performance

• Caching: Cache Blade templates and database queries:

  // config/cache.php
  'default' => env('CACHE_DRIVER', 'file'),
  

• Asset Optimization: Use Laravel Mix/Vite to purge unused CSS/JS:

  mix.purgeCss('public/css/app.css', {
      globs: [
          'resources/css/**/*.css',
          'resources/views/**/*.blade.php',
      ],
  });
  

Extending Functionality

• Custom Blocks: Create new block types:

  // app/Models/ContentBlockType.php
  public static function boot()
  {
      parent::boot();
      static::created(function ($block) {
          if ($block->type === 'custom') {
              // Handle custom logic
          }
      });
  }
  

• Hooks/Events: Listen to theme events:

  // app/Providers/EventServiceProvider.php
  protected $listen = [
      \Appdezign\LaraProBaseTheme\Events\PageRendering::class => [
          \App\Listeners\LogPageRender::class,
      ],
  ];
  

Gotchas and Tips

Pitfalls

1. Template Override Conflicts:

   • Issue: Overriding theme templates may break if the theme updates its structure.
   • Fix: Use @extends and @section carefully. Document overrides in a README.md:

     # Template Overrides
     - `resources/views/vendor/lara-pro-base-theme/layouts/master.blade.php` (custom header/footer)
     - `resources/views/vendor/lara-pro-base-theme/pages/blog.blade.php` (blog-specific layout)
     

2. Asset Naming Collisions:

   • Issue: Theme CSS/JS files may conflict with existing assets (e.g., app.css vs. lara-pro-base-theme.css).
   • Fix: Rename or combine assets in your build process:

     // webpack.mix.js
     mix.sass('resources/scss/app.scss', 'public/css')
         .sass('resources/scss/lara-pro-base-theme.scss', 'public/css/theme.css');
     

3. Database Schema Mismatches:

   • Issue: The theme expects specific table structures (e.g., pages, content_blocks).
   • Fix: Run the theme’s migrations or adapt your schema:

     php artisan migrate --path=/vendor/appdezign/lara-pro-base-theme/database/migrations
     

     Or manually adjust your migrations to match the theme’s schema.

4. Filament Version Conflicts:

   • Issue: The theme requires Filament 5, which may conflict with your app’s Filament version.
   • Fix: Pin the Filament version in composer.json:

     "filament/filament": "^5.0"
     

5. Livewire/Alpine.js Conflicts:

   • Issue: The theme may include its own Livewire/Al