Rock Bundle Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation

   composer require braunstetter/rock-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Braunstetter\RockBundle\RockBundle::class => ['all' => true],
   ];
   

2. Enable Twig Extensions Ensure TwigBundle is installed and configured in config/packages/twig.yaml:

   twig:
       paths: ['%kernel.project_dir%/templates']
       globals:
           rock: '@rock'
   

3. Basic Integration Extend the base template in templates/base.html.twig:

   {% extends 'rock/base.html.twig' %}
   {% block rock_content %}{% endblock %}
   

4. First Use Case Override the sidebar menu in templates/rock/sidebar.html.twig:

   {% extends 'rock/_sidebar.html.twig' %}
   {% block rock_sidebar_menu %}
       {{ parent() }}
       <li><a href="{{ path('app_home') }}">Custom Link</a></li>
   {% endblock %}
   

Implementation Patterns

Core Workflows

1. Extending the Control Panel

   • Override Twig blocks in templates/rock/:
     • base.html.twig (layout)
     • sidebar.html.twig (navigation)
     • user_menu.html.twig (top-right menu)
   • Use {% block rock_[feature] %} to inject content.

2. Dynamic Menu Items Add items via Twig or controller:

   {% block rock_sidebar_menu %}
       {{ parent() }}
       {% for item in app.rock.menu_items %}
           <li><a href="{{ item.path }}">{{ item.label }}</a></li>
       {% endfor %}
   {% endblock %}
   

3. Stimulus Integration Leverage built-in Stimulus controllers (e.g., rock-toggle) for interactive elements:

   <div data-controller="rock-toggle" data-rock-toggle-target="menu">
       <!-- Toggle logic -->
   </div>
   

4. Responsive Design Use rock-responsive classes (e.g., rock-responsive--mobile) for conditional styling.

Integration Tips

• Symfony Security: Pair with make:auth for user management.
• Custom Assets: Override CSS/JS in assets/rock/ (processed via Webpack Encore).
• API-Driven Menus: Fetch menu items via controller and pass to Twig:

  // src/Controller/RockController.php
  public function menuItems(): array
  {
      return [
          ['path' => 'home', 'label' => 'Home'],
          ['path' => 'dashboard', 'label' => 'Dashboard'],
      ];
  }
  

Gotchas and Tips

Pitfalls

1. Twig Block Conflicts

   • Override blocks after calling {{ parent() }} to preserve default content.
   • Example:

     {% block rock_header %}
         {{ parent() }} <!-- Renders default header -->
         <div>Custom Header</div>
     {% endblock %}
     

2. Stimulus Controller Naming

   • Prefix custom Stimulus controllers with rock- (e.g., rock-custom) to avoid conflicts.

3. Missing Documentation

   • Refer to Symfony’s Twig and Stimulus docs for advanced use cases.

4. Asset Pipeline

   • Ensure Webpack Encore is configured if extending CSS/JS. Default assets are in vendor/braunstetter/rock-bundle/resources/.

Debugging

• Template Debugging: Enable Twig debug mode in config/packages/dev/twig.yaml:

  twig:
      debug: true
  

• Stimulus Debugging: Check browser console for Stimulus errors (e.g., missing controllers).

Extension Points

1. Custom User Menu Override templates/rock/user_menu.html.twig and inject Symfony’s security context:

   {% if app.user %}
       <span>Welcome, {{ app.user.username }}</span>
   {% endif %}
   

2. Dynamic Theming Use Twig globals to pass theme variables:

   # config/packages/twig.yaml
   twig:
       globals:
           rock_theme: 'dark'
   

   Then in Twig:

   {% if rock_theme == 'dark' %}
       <link rel="stylesheet" href="{{ asset('css/rock-dark.css') }}">
   {% endif %}
   

3. Localization Extend translation files in translations/rock.en.yaml for menu labels or messages.

4. Event Listeners Hook into RockBundle events (if documented) or create custom events for extensibility.