Tabler Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require kevinpapst/tabler-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       KevinPapst\TablerBundle\TablerBundle::class => ['all' => true],
   ];
   

2. Basic Usage Generate a new controller with the default layout:

   php bin/console make:controller Admin/Dashboard --layout=tabler
   

   Or manually extend the base template in templates/base.html.twig:

   {% extends 'tabler/layout.html.twig' %}
   

3. First Component Use Tabler’s built-in components in Twig:

   {{ tabler_card('Card Title', 'This is a card body') }}
   

Key Entry Points

• Documentation: Start with docs/index.md for setup and API.
• Demo App: Clone TablerBundle-Demo for real-world examples.
• Twig Helpers: Check Resources/views/macros.html.twig for available macros.

Implementation Patterns

Layout Integration

1. Default Layouts Use the pre-built layouts (vertical or horizontal) by extending:

   {% extends 'tabler/layout_vertical.html.twig' %}
   

   Customize via Twig blocks (e.g., body, sidebar).

2. Dynamic Layouts Switch layouts per route using Symfony’s layout option in routing:

   # config/routes.yaml
   admin_dashboard:
       path: /admin
       controller: App\Controller\Admin\DashboardController::index
       defaults:
           layout: 'tabler/layout_horizontal'
   

3. Nested Views Leverage Twig’s embed for reusable sections (e.g., modals, alerts):

   {% embed 'tabler/_partials/modal.html.twig' %}
       {% block modal_title %}Confirm Action{% endblock %}
       {% block modal_body %}Are you sure?{% endblock %}
   {% endembed %}
   

Component Workflows

1. Card-Based UI Use tabler_card() for consistent cards:

   {{ tabler_card('Stats', [
       tabler_card_header('Total Users'),
       tabler_card_body('1,234')
   ]) }}
   

2. Forms with Tabler Styling Extend Symfony’s form themes with Tabler classes:

   {% form_theme form 'tabler/form_theme.html.twig' %}
   

   Override templates in templates/tabler/form/ to customize inputs.

3. Tables & Data Grids Use tabler_table() for responsive tables:

   {{ tabler_table(users, [
       { label: 'Name', value: 'username' },
       { label: 'Role', value: 'roles|join(", ")' }
   ]) }}
   

Asset Management

1. CSS/JS Integration Bundle assets via Webpack Encore or Symfony’s asset mapper:

   // webpack.config.js
   Encore
       .addEntry('tabler', './assets/tabler.js')
       .copyFiles({
           from: './vendor/kevinpapst/tabler-bundle/public',
           to: 'build/[path][name].[ext]'
       });
   

2. Custom Themes Override SCSS variables in assets/scss/tabler/_variables.scss:

   $tabler-primary: #6366f1; // Custom primary color
   

Gotchas and Tips

Common Pitfalls

1. Asset Paths

   • Issue: Missing CSS/JS after install.
   • Fix: Run composer require symfony/webpack-encore-bundle and rebuild assets:

     yarn install && yarn build
     

   • Alternative: Use Symfony’s asset mapper (Symfony 5.3+) for automatic versioning.

2. Twig Macro Conflicts

   • Issue: tabler_card() or other macros not found.
   • Fix: Ensure the bundle is loaded before your app’s Twig extensions:

     // config/bundles.php
     return [
         KevinPapst\TablerBundle\TablerBundle::class => ['all' => true],
         // YourBundle::class => ['all' => true], // Move after TablerBundle
     ];
     

3. Layout Overrides

   • Issue: Custom layout not applying.
   • Fix: Clear cache and verify the template path:

     php bin/console cache:clear
     

   • Debug: Check if templates/base.html.twig correctly extends tabler/layout.html.twig.

Debugging Tips

1. Twig Debugging Enable Twig debugging in .env:

   TWIG_DEBUG=1
   

   Use {{ dump(_context) }} to inspect available macros.

2. Component Inspection

   • Tool: Open browser dev tools (F12) and inspect elements to verify classes (e.g., .card, .table).
   • Tip: Tabler uses Tailwind-like utilities, so check the docs for class names.

Extension Points

1. Custom Macros Extend Twig macros in templates/tabler/macros.html.twig:

   {% macro tabler_custom_component(content) %}
       <div class="custom-component">
           {{ content }}
       </div>
   {% endmacro %}
   

2. Layout Modifications Override layout files in templates/tabler/ (e.g., layout_vertical.html.twig) to modify headers, footers, or sidebars.

3. Symfony Integration

   • Security: Use Tabler’s security layouts (login.html.twig, register.html.twig) with Symfony’s security component:

     # config/packages/security.yaml
     firewalls:
         main:
             form_login:
                 template: 'tabler/security/login.html.twig'
     

   • Menu Builder: Integrate with KnpMenuBundle for dynamic navigation:

     {{ knp_menu_render('main_menu', { template: 'tabler/_partials/nav.html.twig' }) }}
     

Performance Tips

1. Lazy-Load Components Use dynamic imports for heavy components (e.g., charts):

   // assets/tabler.js
   import('tabler-chart').then(module => {
       module.init();
   });
   

2. Asset Optimization

   • Critical CSS: Inline critical Tabler CSS in base.html.twig:

     <style>{{ asset('build/tabler-critical.css')|raw }}</style>
     

   • Defer JS: Load non-critical JS with defer:

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

Configuration Quirks

1. Theme Variables

   • Issue: Theme colors not updating.
   • Fix: Recompile SCSS after modifying _variables.scss:

     yarn encore dev --watch
     

2. Demo App Gaps

   • Tip: The demo app uses Symfony’s make:crud for data management. Replicate with:

     php bin/console make:crud User
     

   • Note: Customize the generated CRUD templates to match Tabler’s styling.

3. Symfony 6+ Gotchas

   • Asset Component: If using Symfony 6’s asset mapper, ensure public/ is symlinked:

     php bin/console assets:install public