Backend Design Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require amaxlab/backend-design-bundle
   

2. Register Bundles in config/bundles.php (or AppKernel.php for older Laravel/Symfony versions):

   return [
       // ...
       Knp\Bundle\MenuBundle\KnpMenuBundle::class,
       Mopa\Bundle\BootstrapBundle\MopaBootstrapBundle::class,
       AmaxLab\Bundle\BackendDesignBundle\BackendDesignBundle::class,
   ];
   

3. Extend Base Template in your Twig templates:

   {% extends "BackendDesignBundle::base.html.twig" %}
   

4. Compile Assets (Laravel 5.5+ uses Webpack; for older Symfony/Laravel, use Assetic):

   php artisan assets:install --symlink
   npm run dev  # or `php artisan assetic:dump` for Assetic
   php artisan cache:clear
   

First Use Case

Create a simple admin page (resources/views/admin/dashboard.html.twig):

{% extends "BackendDesignBundle::base.html.twig" %}

{% block content %}
    <h1>{{ page_title }}</h1>
    <p>Welcome to the backend!</p>
{% endblock %}

Override page_title in your controller:

return $this->render('admin/dashboard.html.twig', [
    'page_title' => 'Dashboard',
]);

Implementation Patterns

1. Template Inheritance & Blocks

Leverage Twig’s block system to customize sections without rewriting the entire template:

{% block before_main_header %}
    <div class="alert alert-info">Custom header content</div>
{% endblock %}

{% block aside_navbar_nav %}
    <ul class="nav navbar-nav">
        <li><a href="{{ path('admin_users') }}">Users</a></li>
        <li><a href="{{ path('admin_posts') }}">Posts</a></li>
    </ul>
{% endblock %}

2. Dynamic Navigation

Use KnpMenuBundle for dynamic menus (define in config/menus.yml):

main_menu:
    items:
        dashboard:
            label: Dashboard
            uri: '#'
        users:
            label: Users
            uri: 'admin_users'

Render in Twig:

{{ knp_menu_render('main_menu', { 'depth': 1 }) }}

3. Gravatar Integration

Enable in config/packages/backend_design.yaml:

backend_design:
    gravatar: true

Use in templates:

<img src="{{ gravatar(user.email, 50) }}" alt="User Avatar">

4. Pagination

Override KnpPaginator templates:

# config/packages/knp_paginator.yaml
knp_paginator:
    template:
        pagination: BackendDesignBundle:Pagination:sliding.html.twig

Render paginated results:

{{ knp_pagination_render(page) }}

5. Asset Management

Extend CSS/JS blocks:

{% block stylesheets %}
    {{ parent() }}  {# Include parent styles #}
    <link rel="stylesheet" href="{{ asset('css/custom.css') }}">
{% endblock %}

Gotchas and Tips

Pitfalls

1. Asset Compilation:

   • Laravel 5.5+ uses Webpack by default. If using Assetic, ensure assetic/assetic-bundle is installed and configured.
   • Symlink assets for development:

     php artisan assets:install --symlink
     

   • Clear cache after changes:

     php artisan cache:clear && php artisan config:clear
     

2. Twig Template Paths:

   • Always extend BackendDesignBundle::base.html.twig. Directly extending base.html.twig in templates/ will break inheritance.
   • Use {{ parent() }} to include parent block content when overriding.

3. Bootstrap Version:

   • The bundle uses Bootstrap 3 (via mopa/bootstrap-bundle). For Bootstrap 4/5, manually override CSS/JS or fork the bundle.

4. Gravatar HTTPS:

   • Force HTTPS for Gravatar by passing true as the 5th parameter:

     {{ gravatar(user.email, 50, 'g', 'mm', true) }}
     

5. MenuBundle Deprecation:

   • KnpMenuBundle is outdated. For modern Laravel, consider symfony/ux-menu-maker-bundle or manually render menus.

Debugging Tips

• Template Errors: Use Twig’s {% block debug %}{% endblock %} to inspect variables.
• Asset Loading: Check browser dev tools for 404s on CSS/JS. Run php artisan assets:install if missing.
• Cache Issues: Clear all caches after config changes:

  php artisan cache:clear
  php artisan config:clear
  

Extension Points

1. Customize Layout:

   • Override base.html.twig in templates/ to modify the entire structure.
   • Example: Add a footer by extending body_end.

2. Add New Blocks:

   • Extend the template to include new sections (e.g., {% block custom_sidebar %}{% endblock %}).

3. Modify Bootstrap Components:

   • Override partials like _navbar.html.twig in templates/BackendDesignBundle/ (create the directory if missing).

4. Integrate with Laravel Mix:

   • Replace Assetic with Laravel Mix by copying compiled assets to public/ and updating Twig paths:

     <link rel="stylesheet" href="{{ mix('css/app.css') }}">
     

5. Localization:

   • Translate static strings (e.g., "Dashboard") using Symfony’s translation system or Laravel’s @lang directives.

Performance Notes

• Asset Optimization: Use Laravel Mix to concatenate/minify CSS/JS in production.
• Gravatar Caching: Cache Gravatar URLs in Redis/Memcached to avoid repeated HTTP requests:

  // In a service
  $cache->remember("gravatar_{$email}_{$size}", 3600, function() use ($email, $size) {
      return gravatar($email, $size);
  });