Theme Twitter Bootstrap 3 Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require elao/theme-twitter-bootstrap-3-bundle
   

   Enable it in config/bundles.php:

   Elao\Theme\TwitterBootstrap3Bundle\ElaoThemeTwitterBootstrap3Bundle::class => ['all' => true],
   

2. Basic Configuration Override the default theme in app/config/config.yml:

   elao_theme:
       theme: "ElaoThemeTwitterBootstrap3Bundle::default"
   

3. First Use Case Extend a base template (e.g., base.html.twig) to leverage Bootstrap 3 classes:

   {% extends 'ElaoThemeTwitterBootstrap3Bundle::base.html.twig' %}
   {% block body %}
       <div class="container">
           <h1 class="page-header">Welcome</h1>
           <div class="alert alert-success">Bootstrap 3 is ready!</div>
       </div>
   {% endblock %}
   

Implementation Patterns

1. Template Inheritance & Overrides

• Extend Base Templates: Use ElaoThemeTwitterBootstrap3Bundle::* as parent templates (e.g., base.html.twig, layout.html.twig).
• Override Blocks: Customize Bootstrap components via Twig blocks:

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

2. Form Integration

• Bootstrap Form Types: Use Symfony’s form themes to auto-generate Bootstrap-compatible forms:

  {% form_theme form '_ElaoThemeTwitterBootstrap3Bundle:Form:bootstrap_3_layout.html.twig' %}
  

• Custom Form Fields: Extend the bundle’s form templates (e.g., form_div_layout.html.twig) in your project’s Resources/views/Form/.

3. Asset Management

• CSS/JS Bundling: Leverage Symfony’s asset system to include Bootstrap’s assets:

  {% block javascripts %}
      {{ parent() }}
      {{ encore_entry_link_tags('app') }} {# For Webpack Encore #}
  {% endblock %}
  

• Custom Assets: Override resources/public/ to include custom Bootstrap extensions (e.g., bootstrap-custom.css).

4. Responsive Layouts

• Use Bootstrap’s grid system (row, col-*) in Twig:

  <div class="row">
      <div class="col-md-6">Left Column</div>
      <div class="col-md-6">Right Column</div>
  </div>
  

• Media Queries: Extend the bundle’s SCSS (if using Webpack Encore) to add custom breakpoints.

5. Integration with Symfony Components

• KnpuOAuth2: Style OAuth buttons with Bootstrap classes:

  <a href="{{ path('connect', {'service': 'github'}) }}" class="btn btn-primary">
      Connect with GitHub
  </a>
  

• VichUploader: Style file upload components:

  <div class="form-group">
      {{ form_widget(form.file, {'attr': {'class': 'form-control'}}) }}
  </div>
  

Gotchas and Tips

Pitfalls

1. Deprecated Bundle

   • Last updated in 2016 (Bootstrap 3 is outdated; consider Bootstrap 5 or Symfony UX Turbo).
   • Workaround: Fork the repo and update dependencies (e.g., twig, symfony/form).

2. Asset Conflicts

   • If using Webpack Encore, manually include Bootstrap 3 via:

     // webpack.config.js
     Encore
         .addEntry('app', './assets/app.js')
         .enableSassLoader()
         .copyFiles({
             from: './node_modules/bootstrap/dist/css/bootstrap.min.css',
             to: 'css/[name].[ext]'
         });
     

3. Twig Template Caching

   • Clear cache after overriding templates:

     php bin/console cache:clear
     

4. Form Theme Paths

   • Ensure form themes are in Resources/views/Form/ or configure custom paths in config.yml:

     twig:
         form_themes:
             - '@ElaoThemeTwitterBootstrap3/Form/bootstrap_3_layout.html.twig'
             - 'Form/bootstrap_extensions.html.twig'
     

Debugging Tips

• Check Loaded Templates: Use Twig’s debug toolbar to verify template inheritance.
• Inspect CSS/JS: Open browser dev tools to confirm assets are loaded (e.g., bootstrap.min.css).
• Symfony Profiler: Debug form rendering issues with the Web Profiler’s "Forms" tab.

Extension Points

1. Custom SCSS Variables Override Bootstrap variables by extending the bundle’s SCSS:

   // assets/scss/custom.scss
   @import "~bootstrap-sass/assets/stylesheets/bootstrap/scss/variables";
   $btn-default-bg: #6c757d; // Customize default button color
   @import "~bootstrap-sass/assets/stylesheets/bootstrap/scss/bootstrap";
   

2. New Components Create reusable Twig components (e.g., components/card.html.twig):

   {# Usage #}
   {% include 'components/card.html.twig' with {
       'title': 'Card Title',
       'content': 'Card content here'
   } %}
   

3. JavaScript Extensions Use Symfony’s asset system to add custom JS:

   {% block javascripts %}
       {{ parent() }}
       <script src="{{ asset('js/custom-bootstrap.js') }}"></script>
   {% endblock %}
   

Performance Quirks

• Asset Fingerprinting: Disable for development to avoid cache issues:

  # config/packages/asset.yaml
  assets:
      version: 'unique_id' # Disable fingerprinting
  

• Lazy Loading: For large projects, lazy-load Bootstrap JS:

  <script src="{{ asset('js/bootstrap.min.js') }}" defer></script>