Gluggi Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require becklyn/gluggi-bundle
   

   Ensure the bundle is registered in config/bundles.php (Symfony 4.4+):

   return [
       // ...
       Becklyn\GluggiBundle\GluggiBundle::class => ['all' => true],
   ];
   

2. Routing: Add to config/routes.yaml (or config/routes/dev.yaml for dev-only):

   layout:
       resource: "@GluggiBundle/Resources/config/routes.yaml"
       prefix: /_layout/
   

3. First Use Case: Create a layout file (e.g., templates/layouts/base.html.twig) and reference it in your Twig templates:

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

Key Configuration

Define in config/packages/gluggi.yaml (or config/config.yaml for Symfony <5.1):

becklyn_gluggi:
    layout_dir: '@Layout'  # Default: '@Layout' (relative to twig.paths)
    css: ['@Assets/css/gluggi.css']  # Uses `becklyn/assets-bundle` namespacing
    js: ['@Assets/js/gluggi.js']
    info_action: 'app.layout_info'  # Route to render layout metadata
    title: 'My Project'

Initial Preview

Access the preview at /_layout/preview (dev-only). Use the gluggi:preview command to generate static previews:

php bin/console gluggi:preview --output=public/previews

Implementation Patterns

Modular Layout Structure

1. Directory Layout: Organize layouts hierarchically (e.g., templates/layouts/{module}/{name}.html.twig). Example:

   templates/
   ├── layouts/
   │   ├── base.html.twig
   │   ├── admin/
   │   │   ├── dashboard.html.twig
   │   │   └── settings.html.twig
   │   └── public/
   │       └── home.html.twig
   

2. Extending Layouts: Use Twig’s {% extends %} with namespaced paths:

   {% extends '@Layout/admin/dashboard.html.twig' %}
   {% block content %}Custom content{% endblock %}
   

Dynamic Asset Loading

Leverage css, js, and js_head in config to auto-load assets:

becklyn_gluggi:
    css:
        - '@Assets/css/admin.css'
        - '@Assets/css/fonts.css'
    js:
        - '@Assets/js/admin.js'
    js_head:
        - '@Assets/js/analytics.js'

Integration with Assets Bundle

Use becklyn/assets-bundle for asset management:

1. Configure asset paths in config/packages/becklyn_assets.yaml:

   becklyn_assets:
       paths:
           images: '%kernel.project_dir%/public/uploads/images'
           css: '%kernel.project_dir%/public/build/css'
   

2. Reference assets in Gluggi config:

   becklyn_gluggi:
       css: ['@Assets/css/main.css']
   

Preview Workflow

1. Static Previews: Generate previews for documentation or client reviews:

   php bin/console gluggi:preview --output=docs/previews --layout=@Layout/admin/dashboard
   

2. Live Preview: Use the /_layout/preview endpoint to test layouts in real-time with dynamic data.

Twig Integration

1. Layout Metadata: Access layout info in Twig via gluggi_layout global variable:

   <title>{{ gluggi_layout.title }} | {{ parent() }}</title>
   

2. Conditional Blocks: Override blocks conditionally:

   {% block sidebar %}
       {% if app.request.attributes.get('_route') == 'admin_dashboard' %}
           {{ include('@Layout/admin/sidebar.html.twig') }}
       {% endif %}
   {% endblock %}
   

Gotchas and Tips

Common Pitfalls

1. Twig Path Namespacing:

   • Use @Layout/ prefix for paths (e.g., @Layout/base.html.twig).
   • Avoid hardcoding templates/ in paths; rely on Symfony’s namespacing.
   • Fix: If using legacy paths, ensure layout_dir in config points to the correct namespace.

2. Asset Loading Issues:

   • Ensure becklyn/assets-bundle is installed (composer require becklyn/assets-bundle).
   • Debug: Check public/build/ or var/cache/dev/ for missing assets.
   • Fix: Verify asset paths in becklyn_assets.yaml and clear cache:

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

3. Preview Route Conflicts:

   • The /_layout/preview route may conflict with other bundles.
   • Fix: Override the route in your routing.yaml:

     gluggi_preview:
         path: /my-custom-preview
         controller: Becklyn\GluggiBundle\Controller\PreviewController::previewAction
     

4. Caching Headaches:

   • Gluggi caches previews aggressively. Clear cache after layout changes:

     php bin/console cache:clear
     php bin/console gluggi:clear-cache
     

Debugging Tips

1. Enable Debug Mode: Set debug: true in config/packages/gluggi.yaml to log layout loading:

   becklyn_gluggi:
       debug: true
   

2. Check Layout Loading: Use Twig’s dump() to inspect loaded layouts:

   {{ dump(gluggi_layout) }}
   

3. Command-Line Flags:

   • List available layouts:

     php bin/console gluggi:list-layouts
     

   • Preview a specific layout:

     php bin/console gluggi:preview --layout=@Layout/admin/dashboard
     

Extension Points

1. Custom Preview Actions: Override the info_action to extend preview functionality:

   becklyn_gluggi:
       info_action: 'app.custom_layout_info'
   

   Create a controller:

   // src/Controller/CustomLayoutController.php
   namespace App\Controller;
   use Becklyn\GluggiBundle\Event\LayoutInfoEvent;
   use Symfony\Component\HttpFoundation\Response;
   use Symfony\Component\Routing\Annotation\Route;
   
   class CustomLayoutController {
       #[Route('/custom-layout-info', name: 'app.custom_layout_info')]
       public function info(LayoutInfoEvent $event): Response {
           $event->addData(['custom_field' => 'value']);
           return new Response('Custom info');
       }
   }
   

2. Event Listeners: Subscribe to Gluggi events to modify behavior:

   // src/EventListener/GluggiListener.php
   namespace App\EventListener;
   use Becklyn\GluggiBundle\Event\LayoutEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class GluggiListener implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [
               LayoutEvent::PRE_LOAD => 'onPreLoad',
           ];
       }
   
       public function onPreLoad(LayoutEvent $event) {
           $event->setLayoutPath('@Layout/custom/' . $event->getLayoutPath());
       }
   }
   

3. Twig Extensions: Create custom Twig functions/filters for Gluggi:

   // src/Twig/AppExtension.php
   namespace App\Twig;
   use Twig\Extension\AbstractExtension;
   use Twig\TwigFunction;
   
   class AppExtension extends AbstractExtension {
       public function getFunctions() {
           return [
               new TwigFunction('gluggi_current_layout', [$this, 'getCurrentLayout']),
           ];
       }
   
       public function getCurrentLayout() {
           // Logic to fetch current layout
           return 'current-layout';
       }
   }
   

   Register in config/packages/twig.yaml:

   twig:
       globals:
           app_extension: '@App\Twig\AppExtension'
   

Performance Tips

1. Asset Optimization: Use becklyn/assets-bundle to concatenate/minify assets:

   becklyn_assets:
       build:
           css: true
           js: true
   

2. Preview Caching: Disable preview caching in dev:

   becklyn_gluggi:
       preview_cache: false
   

3. Layout Inheritance: Avoid deep inheritance chains (e.g., base.html.twig → admin/base.html.twig → dashboard.html.twig). Use includes for modularity:

   {% include '@Layout/_partials/admin-header.html.twig' %}