Admin Ui Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require elasticms/admin-ui-bundle
   

   Add to config/app.php under providers:

   Elasticms\AdminUIBundle\AdminUIServiceProvider::class,
   

   Publish assets and config:

   php artisan vendor:publish --provider="Elasticms\AdminUIBundle\AdminUIServiceProvider" --tag="config"
   php artisan vendor:publish --provider="Elasticms\AdminUIBundle\AdminUIServiceProvider" --tag="assets"
   

2. First Use Case:

   • Enable a built-in admin module (e.g., ContentTypes or MediaLibrary) by configuring config/admin-ui.php:

     'modules' => [
         'content_types' => true,
         'media_library' => true,
     ],
     

   • Access the admin panel at /admin (route defined in the bundle).

3. Key Files to Inspect:

   • config/admin-ui.php: Central configuration for modules, navigation, and theming.
   • resources/views/vendor/admin-ui/: Override default Blade templates here.
   • routes/admin.php: Extend or modify admin routes.

Implementation Patterns

Core Workflows

1. Module Integration

• Enable/Disable Modules: Toggle modules in config/admin-ui.php under the modules key. Example:

  'modules' => [
      'users' => [
          'enabled' => true,
          'icon' => 'fas fa-user',
          'order' => 1,
      ],
  ],
  

• Custom Module Development: Extend the bundle’s module system by creating a service provider and registering it in config/admin-ui.php:

  'custom_modules' => [
      \App\Admin\CustomModule\CustomModuleServiceProvider::class,
  ],
  

2. Navigation and Layouts

• Dynamic Navigation: Configure the admin sidebar via config/admin-ui.php:

  'navigation' => [
      'items' => [
          [
              'label' => 'Content',
              'icon' => 'fas fa-file-alt',
              'route' => 'admin.content_types.index',
              'children' => [
                  ['label' => 'Posts', 'route' => 'admin.posts.index'],
              ],
          ],
      ],
  ],
  

• Layout Overrides: Override the main layout by publishing and modifying:

  php artisan vendor:publish --provider="Elasticms\AdminUIBundle\AdminUIServiceProvider" --tag="views"
  

  Edit resources/views/vendor/admin-ui/layouts/app.blade.php.

3. CRUD Operations

• Leverage ElasticMS Models: The bundle auto-detects ElasticMS models (e.g., ContentType, Media) and generates CRUD interfaces. Customize behavior via:

  'crud' => [
      'ContentType' => [
          'columns' => ['name', 'handle', 'description'],
          'edit' => [
              'exclude_fields' => ['created_at', 'updated_at'],
          ],
      ],
  ],
  

• Custom Controllers: For non-ElasticMS models, create a controller extending Elasticms\AdminUIBundle\Http\Controllers\AdminController:

  namespace App\Http\Controllers\Admin;
  
  use Elasticms\AdminUIBundle\Http\Controllers\AdminController;
  
  class PostsController extends AdminController
  {
      protected $model = \App\Models\Post::class;
  }
  

4. Asset Management

• Extend CSS/JS: Add custom assets in resources/assets/admin/ and include them in resources/views/vendor/admin-ui/layouts/app.blade.php:

  @stack('admin-scripts')
  

• Vue Components: The bundle uses Vue for dynamic features. Extend by publishing and modifying:

  php artisan vendor:publish --provider="Elasticms\AdminUIBundle\AdminUIServiceProvider" --tag="vue"
  

5. Authentication and Authorization

• Gate Integration: Use Laravel’s gates/policies to restrict access. Example:

  Gate::define('manage-content', function ($user) {
      return $user->hasRole('admin');
  });
  

  Then restrict a module in config/admin-ui.php:

  'modules' => [
      'content_types' => [
          'enabled' => true,
          'gate' => 'manage-content',
      ],
  ],
  

Integration Tips

1. ElasticMS-Specific Features:

   • Use the bundle’s built-in support for ElasticMS features like:
     • Content Type Management: Auto-generated interfaces for ContentType models.
     • Media Library: Drag-and-drop uploads and galleries.
     • Localization: Built-in support for multi-language content.

2. API-Driven Admin Panels:

   • If your admin panel is API-driven (e.g., fetching data via Laravel Sanctum), configure the bundle to use API endpoints:

     'api' => [
         'enabled' => true,
         'prefix' => 'api/admin',
     ],
     

3. Testing:

   • Test module routes and permissions using Laravel’s testing tools:

     $this->actingAs($adminUser)
          ->get('/admin/content-types')
          ->assertStatus(200);
     

4. Deployment:

   • Ensure assets are compiled during deployment:

     npm run dev  # or `npm run prod` for production
     php artisan admin-ui:assets
     

Gotchas and Tips

Pitfalls

1. ElasticMS Dependency:

   • The bundle assumes ElasticMS is installed. If you’re not using ElasticMS, expect breaking changes or limited functionality. Mitigate by:
     • Forking the bundle and removing ElasticMS-specific logic.
     • Using it as a UI template while replacing backend logic.

2. Asset Compilation:

   • The bundle relies on npm for asset compilation. If you’re not using npm, manually include the precompiled assets from vendor/elasticms/admin-ui-bundle/resources/assets/.

3. Route Conflicts:

   • The bundle registers routes under /admin. Ensure these don’t conflict with existing routes. Use middleware to restrict access:

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

4. Vue Version Mismatch:

   • The bundle uses Vue 2. If your project uses Vue 3, conflicts may arise. Solutions:
     • Downgrade Vue in your project to match the bundle’s version.
     • Override Vue components by publishing and modifying the bundle’s Vue files.

5. Database Migrations:

   • Some modules (e.g., users) may require migrations. Run:

     php artisan migrate
     

     after installation.

6. Caching Issues:

   • Clear Laravel and Vue caches after configuration changes:

     php artisan view:clear
     php artisan cache:clear
     npm run dev
     

Debugging Tips

1. Log Configuration:

   • Enable debug mode in config/admin-ui.php:

     'debug' => env('APP_DEBUG', false),
     

   • Check logs at storage/logs/laravel.log.

2. Template Overrides:

   • If a template isn’t overriding correctly, verify the file structure matches the bundle’s:

     resources/views/vendor/admin-ui/
     ├── layouts/
     │   └── app.blade.php
     ├── modules/
     │   └── content_types/
     │       ├── index.blade.php
     │       └── edit.blade.php
     

3. Module-Specific Issues:

   • Disable modules one by one in config/admin-ui.php to isolate issues:

     'modules' => [
         'content_types' => false, // Disable temporarily
         'media_library' => true,
     ],
     

4. Vue Debugging:

   • Enable Vue devtools in your browser to inspect components and state. Add this to your app.blade.php:

     <script src="https://unpkg.com/vue-devtools"></script>
     

Extension Points

1. Custom Fields:

   • Extend form fields by creating a service provider:

     namespace App\Providers;
     
     use Elasticms\AdminUIBundle\Extensions\FieldExtensionInterface;
     use Illuminate\Support\ServiceProvider;
     
     class CustomFieldProvider extends ServiceProvider
     {
         public function register()
         {
             $this->app->bind(FieldExtensionInterface::class, \App\Extensions\CustomField::class);
         }
     }
     

2. Event Listeners:

   • Listen to admin events (e.g., AdminModuleLoaded) in EventServiceProvider:

     protected $listen = [
         'Elasticms\AdminUIBundle\Events\AdminModuleLoaded' => [
             \App\Listeners\LogAdminModuleLoad::class,
         ],
     ];
     

3. API Extensions:

   • Extend the API by adding routes