H5Bp Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require ajgl/h5bp-bundle
   

   Register the bundle in config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 2/3):

   Ajgl\H5bpBundle\AjglH5bpBundle::class => ['all' => true],
   

2. Enable Twig Templates Import the bundle’s routing and assets in config/packages/twig.yaml (Symfony 4+):

   twig:
       paths:
           '%kernel.project_dir%/vendor/ajgl/h5bp-bundle/Resources/views': h5bp
   

3. First Use Case: Render a Base Template Extend the H5BP layout in your controller or Twig template:

   {% extends 'h5bp/base.html.twig' %}
   {% block title %}My Page Title{% endblock %}
   {% block content %}
       <h1>Hello, H5BP!</h1>
   {% endblock %}
   

Implementation Patterns

Core Workflows

1. Template Inheritance

   • Use base.html.twig as the parent template for all pages.
   • Override blocks like title, head, content, and footer:

     {% block head %}
         {{ parent() }}  {# Inherits default H5BP meta tags #}
         <meta name="theme-color" content="#317EFB">
     {% endblock %}
     

2. Asset Integration

   • Leverage H5BP’s built-in CSS/JS structure:

     {% block stylesheets %}
         {{ parent() }}  {# Loads h5bp.css #}
         {{ encore_entry_link_tags('app') }}  {# For Webpack Encore #}
     {% endblock %}
     

3. Responsive Design

   • Use H5BP’s mobile-first CSS classes (e.g., .skip-link, .visually-hidden) directly in Twig:

     <a href="#main" class="skip-link">{{ 'Skip to content'|trans }}</a>
     

4. Symfony Integration

   • Pass Symfony variables (e.g., app.request) to Twig:

     {% block head %}
         {{ parent() }}
         <title>{{ app.request.get('page_title', 'Default') }}</title>
     {% endblock %}
     

Advanced Patterns

• Custom Layouts: Copy Resources/views/base.html.twig to your project (e.g., templates/base_custom.html.twig) and extend it.
• Dynamic Favicons: Override favicon.ico in public/ or use Twig:

  {% block favicon %}
      <link rel="icon" href="{{ asset('images/favicon-' ~ app.request.get('theme')) }}.ico">
  {% endblock %}
  

Gotchas and Tips

Pitfalls

1. Symfony Version Mismatch

   • The bundle targets Symfony 2.x (see composer.json). For Symfony 4/5, manually adapt Twig paths or fork the bundle.
   • Fix: Use symfony/framework-bundle:^4.0 with a wrapper or replace Twig paths in config/packages/twig.yaml.

2. Asset Path Conflicts

   • H5BP’s CSS/JS may clash with Webpack Encore or other asset pipelines.
   • Fix: Override stylesheets/javascripts blocks entirely:

     {% block stylesheets %}{% endblock %}
     {% block javascripts %}{% endblock %}
     

3. Missing Documentation

   • The Resources/doc/index.md is referenced but not publicly hosted.
   • Workaround: Inspect Resources/views/base.html.twig for block names and structure.

Debugging Tips

• Check Template Hierarchy: Use {{ _context.getParent() }} in Twig to debug inheritance.
• Clear Cache: After modifying Twig templates, run:

  php bin/console cache:clear
  

Extension Points

1. Customize H5BP Variables

   • Pass data via controller:

     return $this->render('my_template.html.twig', [
         'h5bp_custom_vars' => ['analytics_id' => 'UA-12345'],
     ]);
     

   • Access in Twig:

     {% if h5bp_custom_vars.analytics_id %}
         <script>window.gaId = "{{ h5bp_custom_vars.analytics_id }}";</script>
     {% endif %}
     

2. Override Partial Templates

   • Copy Resources/views/partials/ to templates/partials/ to customize components (e.g., header.html.twig).

3. Add Modern Features

   • Extend with PWA or CSS variables by modifying base.html.twig:

     {% block head %}
         {{ parent() }}
         <style>:root { --primary-color: #317EFB; }</style>
     {% endblock %}