Adminlte Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require kevinpapst/adminlte-bundle:^3.0
   

   Copy default config:

   mkdir -p config/packages && cp vendor/kevinpapst/adminlte-bundle/config/packages/admin_lte.yaml config/packages/
   

2. Enable Bundle: Add to config/bundles.php:

   KevinPapst\AdminLTEBundle\AdminLTEBundle::class => ['all' => true],
   

3. First Use Case: Extend your base template (templates/base.html.twig) with AdminLTE’s layout:

   {% extends 'adminlte:layout.html.twig' %}
   {% block title %}My App{% endblock %}
   {% block body %}{% endblock %}
   

4. Verify Assets: Ensure Webpack Encore is configured (if using assets). Run:

   yarn install && yarn build
   

Implementation Patterns

Core Workflows

1. Layout Customization:

   • Override Twig blocks in adminlte:layout.html.twig (e.g., title, body, sidebar, content_header).
   • Example for a custom sidebar:

     {% block sidebar %}
         {{ knp_menu('menu.main', {
             'rootLink': {'route': 'home'},
             'depth': 2,
             'template': 'adminlte/menu.html.twig'
         }) }}
     {% endblock %}
     

2. Dynamic Menu Integration:

   • Use KNPMenuBundle for dynamic menus. Configure in config/packages/knp_menu.yaml:

     knp_menu:
         twig:
             template: 'adminlte/menu.html.twig'
     

   • Register menu builders in services (services.yaml):

     App\Menu\MainMenuBuilder:
         tags: ['knp_menu.menu_builder', { 'method': 'createMainMenu', 'alias': 'menu.main' }]
     

3. FOSUserBundle Integration:

   • Extend security layouts (templates/security/login.html.twig):

     {% extends 'adminlte/security_layout.html.twig' %}
     {% block body %}
         {{ form_start(form) }}
             {{ form_widget(form._token) }}
             {{ form_widget(form.email) }}
             {{ form_widget(form.password) }}
             <button type="submit">{{ 'security.login.submit'|trans }}</button>
         {{ form_end(form) }}
     {% endblock %}
     

4. Asset Management:

   • Configure Webpack Encore (webpack.config.js) to process AdminLTE assets:

     Encore
         .addEntry('admin', './assets/admin.js')
         .splitEntry('./assets/admin.js')
         .enableSassLoader()
         .enablePostCssLoader();
     

   • Enqueue assets in Twig:

     {{ encore_entry_link_tags('admin') }}
     {{ encore_entry_script_tags('admin') }}
     

5. Event-Driven Customization:

   • Subscribe to AdminLTE events (e.g., AdminLTEEvents::PRE_RENDER) to modify layout dynamically:

     // src/EventListener/AdminLTEListener.php
     public function onPreRender(AdminLTEEvent $event) {
         $event->setLayout('custom_layout');
     }
     

   • Register in services.yaml:

     App\EventListener\AdminLTEListener:
         tags: ['kernel.event_listener', { 'event': 'adminlte.pre_render', 'method': 'onPreRender' }]
     

Gotchas and Tips

Pitfalls

1. Deprecated Features:

   • Avoid using AvanzuAdminThemeBundle patterns (e.g., admin_theme Twig blocks). Use adminlte blocks instead.
   • Example: Replace {% block admin_theme_body %} with {% block body %}.

2. Webpack Encore Conflicts:

   • Ensure webpack.config.js is configured before installing the bundle to avoid asset conflicts.
   • Clear cache after changes:

     yarn build && php bin/console cache:clear
     

3. FOSUserBundle Overrides:

   • Security templates (e.g., login.html.twig) must extend adminlte/security_layout.html.twig, not base.html.twig.
   • Customize FOSUserBundle routes in config/routes.yaml:

     fos_user:
         resource: "@FOSUserBundle/Resources/config/routing/all.xml"
         prefix: /admin
         type: adminlte
     

4. Menu Builder Quirks:

   • KNPMenu templates must match AdminLTE’s structure. Use the provided adminlte/menu.html.twig as a base.
   • Debug menu rendering with:

     {{ dump(knp_menu('menu.main')) }}
     

5. Translation Issues:

   • Ensure translations are loaded in config/packages/translation.yaml:

     translation:
         paths: ['%kernel.project_dir%/translations']
     

   • Add missing translations to translations/messages.en.yaml:

     adminlte:
         layout_title: 'My App Dashboard'
     

Debugging Tips

1. Layout Rendering:

   • Check if adminlte:layout.html.twig is being extended. Use Twig’s {% debug %} block:

     {% debug %}
     

2. Event Dispatching:

   • Verify events are fired by adding a logger:

     public function onPreRender(AdminLTEEvent $event) {
         \Log::info('AdminLTE event triggered', ['layout' => $event->getLayout()]);
     }
     

3. Asset Loading:

   • Clear Symfony and Webpack caches:

     rm -rf var/cache/* && yarn build
     

4. Configuration Overrides:

   • Validate admin_lte.yaml settings. Use the default config as a reference:

     admin_lte:
         layout_theme: 'light-blue'  # Default: 'skin-blue'
         brand_text: 'My App'
     

Extension Points

1. Custom Layouts:

   • Create a new layout by copying vendor/kevinpapst/adminlte-bundle/Resources/views/layout.html.twig to templates/adminlte/layout_custom.html.twig.
   • Override in admin_lte.yaml:

     admin_lte:
         layout: 'layout_custom'
     

2. Dynamic Content Sidebar:

   • Use the control-sidebar block to add dynamic content (e.g., notifications):

     {% block control-sidebar %}
         <div class="control-sidebar-content">
             <ul class="control-sidebar-menu">
                 <li><a href="#"><i class="fas fa-comments"></i> Messages</a></li>
             </ul>
         </div>
     {% endblock %}
     

3. Theming:

   • Override AdminLTE’s SCSS variables in assets/admin.scss:

     $skin-color: #3c8dbc;
     @import '~admin-lte/dist/css/skins/_skin-blue.scss';
     

   • Recompile with Webpack Encore.

4. Custom Commands:

   • Extend AdminLTE commands (e.g., AdminLTE:Assets:Install) by creating a custom command:

     use Symfony\Component\Console\Command\Command;
     use Symfony\Component\Console\Input\InputInterface;
     use Symfony\Component\Console\Output\OutputInterface;
     
     class CustomAdminLTECommand extends Command {
         protected function execute(InputInterface $input, OutputInterface $output) {
             // Custom logic
         }
     }
     

   • Register in services.yaml:

     App\Command\CustomAdminLTECommand:
         tags: ['console.command']