Getting Started

Minimal Setup for Laravel

Install the package:

composer require colorlibhq/adminlte-laravel

Publish assets and config:

php artisan vendor:publish --provider="ColorlibHQ\AdminLTE\AdminLTEServiceProvider" --tag="adminlte-assets"
php artisan vendor:publish --provider="ColorlibHQ\AdminLTE\AdminLTEServiceProvider" --tag="adminlte-config"

Add AdminLTE to your layout: Include the published blade file in your resources/views/layouts/app.blade.php:
```
@extends('adminlte::page')
```

First use case: Create a simple dashboard page at resources/views/dashboard.blade.php:

@extends('adminlte::page')
@section('title', 'Dashboard')
@section('content_header')
    <h1>Dashboard</h1>
@stop
@section('content')
    <p>Welcome to your AdminLTE dashboard!</p>
@stop

Key Files to Review

config/adminlte.php: Customize theme, layout, and menu.
resources/views/vendor/adminlte/: Published blade templates (modify as needed).
Official Laravel Edition Docs.

Implementation Patterns

1. Dynamic Menu Generation

Leverage the config-driven menu system to build navigation dynamically:

// config/adminlte.php
'menu' => [
    [
        'text' => 'Dashboard',
        'url'  => '/dashboard',
        'icon' => 'fas fa-tachometer-alt',
    ],
    [
        'text' => 'Users',
        'url'  => '/users',
        'icon' => 'fas fa-users',
        'submenu' => [
            ['text' => 'List', 'url' => '/users/list'],
            ['text' => 'Create', 'url' => '/users/create'],
        ],
    ],
],

Usage in Blade:

@include('adminlte::menu')

2. Theme Customization

Override default colors/skins via config:

// config/adminlte.php
'skin' => 'blue', // Options: 'blue', 'black', 'purple', 'yellow', 'red', 'green', 'teal', 'orange'
'sidebar_mini' => true, // Collapse sidebar by default

3. Layout Components

Use built-in sections:

@extends('adminlte::page')

@section('title', 'Page Title')
@section('content_header')
    <h1>Header Content</h1>
    <small>Subheader text</small>
@stop

@section('content')
    <!-- Main content -->
@stop

@section('css')
    <link rel="stylesheet" href="/css/custom.css">
@stop

@section('js')
    <script src="/js/custom.js"></script>
@stop

4. Authentication Scaffolding

Generate auth views with:

php artisan adminlte:auth

This creates:

Login/Register/ResetPassword pages
Middleware for guest routes
Blade templates in resources/views/auth/.

5. Widgets and UI Elements

Include pre-built widgets:

<div class="row">
    <div class="col-12 col-sm-6 col-md-3">
        @include('adminlte::widget_box', [
            'title' => 'Quick Example',
            'icon' => 'fa fa-file-code-o',
            'content' => 'Create an amazing page',
        ])
    </div>
</div>

6. Integration with Laravel Mix

Compile custom CSS/JS alongside AdminLTE:

// webpack.mix.js
mix.js('resources/js/app.js', 'public/js')
   .sass('resources/scss/app.scss', 'public/css')
   .copy('node_modules/admin-lte/dist', 'public/admin-lte');

Gotchas and Tips

Pitfalls

Asset Paths:
- After publishing assets, ensure paths in public/admin-lte are correct.
- If using Laravel Mix, exclude AdminLTE’s dist/ from compilation to avoid duplication.
Bootstrap 5 Migration:
- AdminLTE v4 uses Bootstrap 5. Update your custom CSS/JS to use BS5 classes (e.g., data-bs-toggle instead of data-toggle).
- Common issues:
  - .modal classes may need adjustments (e.g., .modal-dialog sizing).
  - Custom dropdowns may break; use data-bs-toggle="dropdown".

Dark Mode:

Enable via config:
```
'dark_mode' => true,
```

Or dynamically with JavaScript:

document.body.setAttribute('data-bs-theme', 'dark');

Sidebar Collapse:

Use data-lte-toggle="sidebar" for manual toggling:

<button class="btn" data-lte-toggle="sidebar">
    <i class="fas fa-bars"></i>
</button>

Debugging Tips

Clear Published Assets: If changes to resources/views/vendor/adminlte/ don’t reflect, clear compiled views:
```
php artisan view:clear
```
Check Config Overrides: Ensure no cached config is overriding your adminlte.php settings:
```
php artisan config:clear
```
JavaScript Conflicts: AdminLTE uses vanilla JS. If plugins fail:
- Verify no jQuery dependencies are loaded.
- Check browser console for errors (e.g., missing adminlte.min.js).
RTL Support: Enable in config:
```
'rtl' => true,
```
Ensure your app’s locale is RTL-compatible (e.g., app.php in Laravel).

Extension Points

Custom Blade Directives: Extend AdminLTE’s directives in AppServiceProvider:

Blade::directive('adminlteBox', function ($expression) {
    return "<?php echo \\ColorlibHQ\\AdminLTE\\Widgets::box($expression); ?>";
});

Override Widgets: Copy resources/views/vendor/adminlte/widgets/ to your project and modify.

Add Custom Plugins: Include third-party plugins in resources/views/layouts/app.blade.php:

@section('extra_css')
    <link rel="stylesheet" href="https://cdn.datatables.net/1.11.5/css/dataTables.bootstrap5.min.css">
@stop

@section('extra_js')
    <script src="https://cdn.datatables.net/1.11.5/js/jquery.dataTables.min.js"></script>
    <script src="https://cdn.datatables.net/1.11.5/js/dataTables.bootstrap5.min.js"></script>
@stop

Dynamic Theming: Change themes via JavaScript:

function setTheme(theme) {
    document.body.setAttribute('data-bs-theme', theme);
    localStorage.setItem('adminlte-theme', theme);
}

Performance Quirks

Avoid Inlining Assets: Use Laravel Mix or Vite to bundle AdminLTE with your app.

Lazy-Load Pages: For large apps, lazy-load non-critical JS:

<script src="/admin-lte/dist/js/adminlte.min.js" defer></script>

Critical CSS: Extract critical CSS for the dashboard to reduce render-blocking.

Laravel-Specific Tips

Route Caching: After adding menu items, regenerate routes:
```
php artisan route:clear
```

Middleware: Protect admin routes with admin middleware (included by default):

Route::middleware(['auth', 'admin'])->group(function () {
    // Admin routes
});

Localization: AdminLTE supports Laravel’s localization. Override translations in resources/lang/.

Testing: Use adminlte::page in feature tests:

$response = $this->actingAs($user)->get('/dashboard');
$response->assertSee('Dashboard');

Adminlte Laravel Package