Admin Theme Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require avanzu/admin-theme-bundle
   

   For Symfony 2.8+, ensure Assetic is installed:

   composer require symfony/assetic-bundle
   

2. Enable the Bundle: Add to config/bundles.php (Symfony 4+) or app/AppKernel.php (Symfony 2/3):

   new Avanzu\AdminThemeBundle\AvanzuAdminThemeBundle(),
   

3. Initialize Assets:

   php bin/console assets:install --symlink
   php bin/console avanzu:admin:initialize
   php bin/console avanzu:admin:fetch-vendor
   

4. First Use Case: Extend the base layout in your controller:

   use Sensio\Bundle\FrameworkExtraBundle\Configuration\Template;
   
   class DashboardController extends Controller
   {
       /**
        * @Template("@AvanzuAdminTheme/Layout/base.html.twig")
        */
       public function indexAction()
       {
           return [];
       }
   }
   

Implementation Patterns

1. Layout Integration

• Base Layout: Extend @AvanzuAdminTheme/Layout/base.html.twig in your templates.

  {% extends '@AvanzuAdminTheme/Layout/base.html.twig' %}
  {% block body %}
      <!-- Your content here -->
  {% endblock %}
  

• Custom Blocks: Override blocks like avanzu_body_start, sidebar, or navbar:

  {% block sidebar %}
      {{ parent() }}
      <li class="treeview">
          <a href="#"><i class="fa fa-dashboard"></i> <span>Dashboard</span></a>
      </li>
  {% endblock %}
  

2. Dynamic Skins & Themes

• Configure globally in config/packages/twig.yaml:

  twig:
      globals:
          admin_skin: "skin-blue-light"  # Default: skin-blue
  

  Or via parameters.yml:

  admin_skin: "%env(ADMIN_SKIN)%"
  

3. Asset Management

• Pre-packaged Assets: No need for Bower/Assetic (unless explicitly enabled).
• Rebuild Assets:

  php bin/console avanzu:admin:rebuild
  

• Disable Assetic (if not needed):

  # config/packages/avanzu_admin_theme.yaml
  avanzu_admin_theme:
      use_assetic: false
  

4. Components & Events

• Navbar Components: Use built-in macros for notifications, messages, or tasks:

  {{ render(controller('AvanzuAdminThemeBundle:Navbar:notifications')) }}
  

• Custom Events: Extend via Twig events (e.g., avanzu.admin.theme.layout.render).

5. Sidebar & Navigation

• Dynamic Menus: Integrate with KnpMenuBundle:

  {{ knp_menu_render('main_menu', {
      'rootName': 'Dashboard',
      'depth': 2,
      'template': '@AvanzuAdminTheme/Sidebar/menu.html.twig'
  }) }}
  

• Configure Menu:

  # config/packages/avanzu_admin_theme.yaml
  avanzu_admin_theme:
      menu:
          main_menu: "main_menu"  # KnpMenu alias
  

6. Form Theming

• Extend the default form theme:

  {% form_theme form '@AvanzuAdminTheme/Form/fields.html.twig' %}
  

• Customize inputs in templates/avanzu_admin_theme/form/fields.html.twig.

7. Authentication (FOSUserBundle)

• Use the built-in login layout:

  {% extends '@AvanzuAdminTheme/Login/login.html.twig' %}
  

Gotchas and Tips

Pitfalls

1. Asset Paths:

   • Hardcoded paths in Resources/public/static/ may break if not symlinked.
   • Fix: Always use --symlink with assets:install.

2. Assetic Conflicts:

   • If Assetic is enabled but unused, disable it in config:

     avanzu_admin_theme:
         use_assetic: false
     

3. Skin Overrides:

   • Global skin settings (admin_skin) override per-page settings.
   • Tip: Use Twig globals for dynamic skins:

     {% set skin = app.global.admin_skin %}
     

4. Bower Dependencies:

   • The bundle locks versions (e.g., ionicons@2.0.1) to avoid breakages.
   • Workaround: Manually update composer.json if needed.

5. Windows Compatibility:

   • avanzu:admin:initialize may fail on Windows. Use WSL or manually copy assets.

6. KnpMenu Integration:

   • Ensure the menu alias matches the KnpMenu configuration:

     knp_menu:
         twig:
             template: '@AvanzuAdminTheme/Sidebar/menu.html.twig'
     

Debugging Tips

1. Clear Cache:

   php bin/console cache:clear
   php bin/console assets:clear
   

2. Check Asset Compilation:

   • Verify public/bundles/avanzuadmintheme/ exists after fetch-vendor.
   • Debug: Run avanzu:admin:rebuild in dev mode.

3. Twig Errors:

   • Enable Twig debug mode:

     twig:
         debug: true
     

   • Check for missing blocks (e.g., avanzu_body_start).

4. Event Dispatching:

   • Listen for avanzu.admin.theme.layout.render to modify the base layout:

     $eventDispatcher->addListener('avanzu.admin.theme.layout.render', function (Event $event) {
         $event->setArgument('custom_var', 'value');
     });
     

Extension Points

1. Custom Templates:

   • Override any template in templates/avanzu_admin_theme/ (e.g., base.html.twig).

2. New Components:

   • Extend the bundle by creating custom Twig macros in Resources/views/Macros/.

3. Configuration:

   • Add to config/packages/avanzu_admin_theme.yaml:

     avanzu_admin_theme:
         layout:
             title: "My App"
             logo: "/path/to/logo.png"
         navbar:
             user_menu: false  # Disable user dropdown
     

4. Translations:

   • Add translations for navbar messages/notifications in translations/messages.en.yaml:

     navbar:
         notifications: "Notifications (%count%)"
     

Performance

• Disable Unused JS/CSS: Use Assetic groups to load only required assets:

  {% block stylesheets %}
      {{ parent() }}
      {{ encore_entry_link_tags('admin') }}
  {% endblock %}
  

• Preload Assets: For production, precompile assets:

  php bin/console assets:install --no-debug
  

Upgrade Notes

• 1.x → 2.x: Requires manual refactoring (template changes).
• Post-Install Script: Add to composer.json to auto-fetch vendors:

  "scripts": {
      "post-install-cmd": ["Avanzu\\AdminThemeBundle\\Composer\\ScriptHandler::fetchThemeVendors"],
      "post-update-cmd": ["Avanzu\\AdminThemeBundle\\Composer\\ScriptHandler::fetchThemeVendors"]
  }