Getting Started

Minimal Setup Steps

Installation

Require the package via Composer:

composer require appdezign/lara-pro-demo-theme

Publish the theme assets and config (if needed):

php artisan vendor:publish --provider="Appdezign\LaraProDemoTheme\LaraProDemoThemeServiceProvider" --tag="public"
php artisan vendor:publish --provider="Appdezign\LaraProDemoTheme\LaraProDemoThemeServiceProvider" --tag="config"

Enable the Theme

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

Set the active theme in .env:
```
CMS_THEME=demo
```

First Use Case: Displaying a Page

Use the CMS facade to fetch and render a page:

use Appdezign\CMS\Facades\CMS;

$page = CMS::page('home');
return view('demo::pages.home', compact('page'));

Ensure your Blade template extends the demo theme layout:
```
@extends('demo::layouts.app')
```

Implementation Patterns

Core Workflows

Child Theme Inheritance
- Override parent theme views by placing files in resources/views/vendor/demo/ (or resources/views/demo/ if using a custom path).
- Example: Override layouts/app.blade.php:
```
cp vendor/appdezign/lara-pro-demo-theme/resources/views/layouts/app.blade.php resources/views/demo/layouts/
```

Dynamic Content Rendering

Use CMS blocks in Blade templates:

{!! $page->blocks()->where('name', 'hero')->render() !!}

Access block data via:

$heroBlock = $page->blocks()->where('name', 'hero')->first();
$heroBlock->data['title']; // Custom field access

Asset Management

Publish and compile assets via Laravel Mix:

// resources/js/demo/app.js
require('./vendor/demo');

Include compiled assets in Blade:

@vite(['resources/js/demo/app.js', 'resources/css/demo/app.css'])

Theme-Specific Routes

Route::get('/custom-route', [DemoController::class, 'index']);

Load routes in AppServiceProvider:

public function boot()
{
    if (config('cms.theme') === 'demo') {
        $this->loadRoutesFrom(__DIR__.'/../routes/demo.php');
    }
}

Configuration Overrides

Extend theme config in config/demo.php:

return [
    'settings' => [
        'default_color' => '#ff0000', // Override parent config
    ],
];

Access via:
```
config('demo.settings.default_color');
```

Integration Tips

Laravel Mix/Vite: Configure aliases in vite.config.js to resolve demo theme assets:

resolve: {
    alias: {
        '@demo': path.resolve(__dirname, 'resources/js/demo'),
    },
},

Livewire/Alpine: Use @stack('demo-scripts') in layouts/app.blade.php to inject theme-specific JS:
```
@stack('demo-scripts')
```
CMS Media: Upload theme-specific assets via the CMS media manager and reference them in blocks:
```
<img src="{{ $block->data['image']->url }}" alt="{{ $block->data['image_alt'] }}">
```

Gotchas and Tips

Pitfalls

Parent Theme Dependencies
- The demo theme relies on the Base Theme. Ensure it’s installed and active if the demo theme fails to load:
```
composer require appdezign/lara-pro-base-theme
```
- Debug missing parent theme assets by checking config/cms.php for the correct parent key.
Asset Path Conflicts
- Avoid naming conflicts with parent theme assets. Prefix demo-specific files (e.g., demo-app.js instead of app.js).
- Clear cached assets after updates:
```
php artisan cache:clear
php artisan view:clear
npm run dev
```

Block Data Serialization

Custom block data may not serialize correctly. Use json_encode/json_decode for complex data:
```
$data = json_decode($block->data['custom_field'], true);
```

Validate block data in AppServiceProvider:

CMS::block('hero')->validate(function ($data) {
    return validator($data, ['title' => 'required|string']);
});

Theme Switching
- Switching themes may break routes/views. Use a feature flag or environment-based theme selection:
```
$theme = env('CMS_THEME', 'demo');
```

Debugging

View Not Found: Ensure Blade templates use the correct namespace (demo:: prefix).

@extends('demo::layouts.app') <!-- Correct -->
@extends('layouts.app')       <!-- Wrong (unless published) -->

Config Overrides: Use php artisan config:clear to reset cached config after changes.
Route Conflicts: Dump routes to debug overlaps:
```
php artisan route:list | grep demo
```

Extension Points

Custom Blocks
- Extend the demo theme with new blocks by publishing the block manager:
```
php artisan vendor:publish --tag="cms-blocks"
```
- Register a custom block in AppServiceProvider:
```
CMS::block('custom_block')->view('demo::blocks.custom');
```

Theme Events

Listen for theme-specific events (e.g., demo.theme.ready):
```
event(new DemoThemeReady);
```

Subscribe in EventServiceProvider:

protected $listen = [
    'Appdezign\LaraProDemoTheme\Events\DemoThemeReady' => [
        DemoThemeListener::class,
    ],
];

API Endpoints

Create theme-specific API routes in routes/api.php:

Route::prefix('demo')->group(function () {
    Route::get('/data', [DemoApiController::class, 'fetchData']);
});

Protect routes with middleware:

Route::middleware(['theme:demo'])->group(function () { ... });

Pro Tips

Local Development: Use php artisan cms:demo (if available) to reset the demo theme to default state.

Performance: Lazy-load demo-specific assets with Alpine.js:

document.addEventListener('alpine:init', () => {
    Alpine.data('demoAssets', () => ({
        load() {
            this.$nextTick(() => {
                require('./vendor/demo/assets');
            });
        },
    }));
});

Testing: Mock the demo theme in PHPUnit:

$this->app->singleton('cms.theme', function () {
    return 'demo';
});

Lara Pro Demo Theme Laravel Package