Admin Theme Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require elao/admin-theme-bundle
   

   Ensure ElaoAdminThemeBundle is enabled in config/bundles.php:

   Elao\AdminThemeBundle\ElaoAdminThemeBundle::class => ['all' => true],
   

2. Extend Base Template: Create templates/base.html.twig in your project:

   {% extends '@ElaoAdminTheme/base.html.twig' %}
   

   Override blocks like stylesheets, javascripts, title, and logo.

3. First Use Case:

   • Define a primary menu (menu_primary) in base.html.twig to render navigation.
   • Use mobile menu (menu_mobile) for responsive layouts.
   • Extend base.html.twig in child templates (e.g., templates/user/base.html.twig).

Implementation Patterns

Core Workflows

1. Template Inheritance:

   • Always extend @ElaoAdminTheme/base.html.twig in your project’s base.html.twig.
   • Override blocks (e.g., stylesheets, javascripts) to inject assets via Encore/Webpack.

2. Menu Configuration:

   • Primary Menu: Define as an array of items with route, label, icon, and root (for grouping).

     {% set menu_primary = [
         { route: 'dashboard', label: 'Dashboard', icon: 'home', root: 'dashboard' }
     ] %}
     

   • Mobile Menu: Nested structure with children for hierarchical navigation.

     {% set menu_mobile = [
         { label: 'Users', root: 'users', children: [...] }
     ] %}
     

3. Dynamic Content:

   • Use Twig’s {% block %} to customize sections (e.g., title, logo, content).
   • Pass variables to child templates via {% set %} (e.g., {% set page_title = 'Users' %}).

4. Asset Integration:

   • Leverage Encore for JavaScript/CSS:

     {% block javascripts %}
         {{ encore_entry_script_tags('app') }}
         {{ encore_entry_script_tags('admin') }} {# Custom admin JS #}
     {% endblock %}
     

5. Routing:

   • Ensure routes are named (e.g., user_list) to reference them in menus.
   • Use url() for external links (e.g., { url: '/logout' }).

Integration Tips

• Symfony Flex: If using Symfony Flex, run composer require and php bin/console cache:clear to auto-configure the bundle.

• Custom Templates: Override specific templates (e.g., @ElaoAdminTheme/partials/navbar.html.twig) in templates/ElaoAdminTheme/partials/ to modify UI components.

• Translation: The bundle supports translations (e.g., menu labels). Extend translation files in translations/:

  # translations/messages.fr.yaml
  menu:
      user_list: 'Liste des utilisateurs'
  

• Debugging: Enable Twig debug mode in .env:

  APP_DEBUG=1
  

Gotchas and Tips

Pitfalls

1. Missing extends: Forgetting to extend @ElaoAdminTheme/base.html.twig will break the layout. Always verify the parent template.

2. Route Mismatches: If a menu item’s route doesn’t exist, the link will 404. Test routes with:

   php bin/console debug:router
   

3. Asset Loading: Ensure Encore is configured (webpack.config.js) and entries are built before testing templates.

4. Mobile Menu Depth: The mobile menu supports 2 levels of nesting (children → children). Exceeding this may break rendering.

5. Caching: Clear Symfony cache after template changes:

   php bin/console cache:clear
   

Debugging Tips

• Twig Errors: Check var/log/dev.log for Twig syntax errors (e.g., unclosed blocks or invalid variables).

• Template Overrides: If custom templates aren’t loading, verify the file structure matches the bundle’s paths (e.g., templates/ElaoAdminTheme/partials/).

• Menu Validation: Use this Twig snippet to debug menu structures:

  {% dump(menu_primary) %}
  {% dump(menu_mobile) %}
  

Extension Points

1. Custom Components: Override partials (e.g., @ElaoAdminTheme/partials/alert.html.twig) in templates/ElaoAdminTheme/partials/.

2. Theme Variables: Extend the theme by adding custom Twig globals in a compiler pass or service:

   // src/EventListener/AddThemeVariables.php
   public function onKernelRequest(GetResponseEvent $event) {
       $twig = $event->getKernel()->getContainer()->get('twig');
       $twig->addGlobal('custom_var', 'value');
   }
   

3. SCSS Overrides: Import the bundle’s SCSS variables in your project’s assets/styles/app.scss:

   @import '~@elao/admin-theme-bundle/scss/variables';
   

4. JavaScript Extensions: Extend the admin JS bundle in webpack.config.js:

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