Layout Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require apnet/layout-bundle:~3.1
   

   Add bundles to AppKernel.php:

   $bundles[] = new Apnet\AsseticImporterBundle\ApnetAsseticImporterBundle();
   $bundles[] = new Apnet\LayoutBundle\ApnetLayoutBundle();
   

2. First Use Case: Extend the base layout in your Twig template:

   {% extends "ApnetLayoutBundle::body.html.twig" %}
   
   {% block title %}My Site{% endblock %}
   

Where to Look First

• Base Template: body.html.twig
• Asset Handling: imported_asset() Twig function (via ApnetAsseticImporterBundle).
• Default Blocks: stylesheets_core, body_core, javascripts_core (see README for structure).

Implementation Patterns

Core Workflow

1. Extending Layouts: Override blocks in child templates (e.g., app/Resources/views/base.html.twig):

   {% extends "ApnetLayoutBundle::body.html.twig" %}
   
   {% block stylesheets_core %}
       {{ parent() }}  {# Include parent styles #}
       <link href="{{ imported_asset('css/custom.css') }}" rel="stylesheet" />
   {% endblock %}
   

2. Asset Management: Use imported_asset() for versioned assets (e.g., imported_asset('bundles/app/js/main.js')). Configure asset paths in config.yml:

   apnet_assetic_importer:
       bundles:
           - AppBundle
   

3. Dynamic Content Injection: Pass variables to the layout via Twig’s {% block %} or controller:

   {% block meta_tags %}
       <meta name="description" content="{{ page_description }}">
   {% endblock %}
   

Integration Tips

• Symfony 3.x/4.x: Works with Symfony 3.0+ (check composer.json constraints).
• Assetic: If using Assetic, ensure ApnetAsseticImporterBundle is configured for asset pipelines.
• Bootstrap/jQuery: Pre-bundled assets are auto-included via stylesheets_core/javascripts_core.

Gotchas and Tips

Pitfalls

1. Bundle Dependency Conflicts:

   • apnet/layout-bundle requires Symfony 2.3/3.0 and Apnet’s Bootstrap/jQuery bundles.
   • Avoid mixing with other layout bundles (e.g., KnpLabs/KnpMenuBundle may conflict with preloaded JS).

2. Asset Paths:

   • imported_asset() fails if assets aren’t in configured bundles (check apnet_assetic_importer.bundles).
   • Debug with {{ dump(asset('path')) }} in Twig.

3. Block Overrides:

   • Forgetting {{ parent() }} removes inherited assets (e.g., Bootstrap CSS).
   • Example of incorrect override:

     {% block stylesheets_core %}  {# Missing parent() #}
         <link href="..." />
     {% endblock %}
     

Debugging

• Twig Errors: Enable Twig debug mode in config.yml:

  twig:
      debug: true
      strict_variables: true
  

• Asset Loading: Clear cache after adding new assets:

  php bin/console cache:clear --env=prod
  

Extension Points

1. Custom Layouts: Override the entire layout by extending a different template (e.g., AcmeBundle::layout.html.twig).

2. Dynamic Blocks: Use Twig’s {% block %} conditionally:

   {% block extra_scripts %}
       {% if app.user %}
           <script src="{{ imported_asset('js/user.js') }}"></script>
       {% endif %}
   {% endblock %}
   

3. Configuration: Extend apnet_layout config (if available) to modify default blocks or asset paths.

Pro Tips

• Versioning: Use imported_asset() for cache-busting (e.g., imported_asset('css/main.css?v=1.2')).
• Performance: Exclude unused blocks (e.g., javascripts_core) if not needed.
• Legacy Support: Works with Symfony 2.3, but test thoroughly for edge cases.