Four Tiles With Text Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Add the bundle via Composer:

   composer require coaladmin/four-tiles-with-text-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       CoalAdmin\FourTilesWithTextBundle\CoalAdminFourTilesWithTextBundle::class => ['all' => true],
   ];
   

2. Basic Usage After installation, the bundle provides a reusable FourTilesWithText component for Symfony UX Live Components. Register it in your controller:

   use CoalAdmin\FourTilesWithTextBundle\Component\FourTilesWithText;
   
   #[Route('/dashboard', name: 'dashboard')]
   public function dashboard(FourTilesWithText $fourTilesWithText): Response
   {
       return $this->render('dashboard.html.twig', [
           'tiles' => $fourTilesWithText->render([
               [
                   'title' => 'Tile 1',
                   'text' => 'Description for Tile 1',
                   'icon' => 'fas fa-chart-bar',
                   'color' => 'primary',
                   'link' => '#',
               ],
               // Repeat for 3 more tiles
           ]),
       ]);
   }
   

3. First Use Case Use the component in a dashboard to display key metrics (e.g., users, orders, revenue) with icons, colors, and links. Example Twig:

   <div class="container">
       {{ tiles|raw }}
   </div>
   

Implementation Patterns

Workflows

1. Dynamic Data Binding Fetch data from a repository/service and pass it to the component:

   $tiles = [
       [
           'title' => 'Total Users',
           'text' => $userService->getTotalUsers(),
           'icon' => 'fas fa-users',
           'color' => 'info',
           'link' => route('users.index'),
       ],
       // ...
   ];
   

2. Reusable Components Create a base template (dashboard.html.twig) to wrap the component:

   {% extends 'base.html.twig' %}
   {% block body %}
       <div class="row">
           {{ tiles|raw }}
       </div>
   {% endblock %}
   

3. Integration with Symfony UX Use with Turbo or Stimulus for real-time updates:

   // stimulus_controller.js
   import { Controller } from '@hotwired/stimulus';
   export default class extends Controller {
       connect() {
           this.element.addEventListener('click', () => {
               // Fetch updated data via API and re-render tiles
           });
       }
   }
   

Tips for Daily Use

• Consistency: Standardize tile colors (primary, secondary, success, etc.) across the app.
• Responsiveness: Use Bootstrap classes (col-md-3) to ensure tiles stack on mobile.
• Localization: Pass translated text for multilingual support:

  'text' => $this->get('translator')->trans('dashboard.users'),
  

Gotchas and Tips

Pitfalls

1. Live Component Requirements Ensure Symfony UX Live Components are installed:

   composer require symfony/ux-live-component
   

   Add to config/packages/framework.php:

   'live_components' => ['*'],
   

2. Twig Security The |raw filter is required for HTML rendering. Avoid passing untrusted data to text or title to prevent XSS.

3. Icon Dependencies The bundle expects Font Awesome icons by default. If using a different icon library (e.g., Bootstrap Icons), override the Twig template or CSS classes.

Debugging

• Missing Tiles: Verify the tiles array has exactly 4 items. The component expects 4 tiles.
• Styling Issues: Check for conflicting CSS. Inspect the rendered HTML to debug layout problems.
• Live Updates: If Turbo/Stimulus isn’t working, ensure:

  {{ stimulus_controller('dashboard', {}) }}
  

  is included in the template.

Extension Points

1. Custom Templates Override the default Twig template (FourTilesWithText.html.twig) by copying it to:

   templates/components/four_tiles_with_text.html.twig
   

2. Additional Fields Extend the tile structure by modifying the component class:

   // src/Component/CustomFourTiles.php
   public function render(array $tiles): string {
       // Add custom logic (e.g., 'badge' field)
   }
   

3. Dynamic Colors Use a service to generate dynamic colors based on data:

   'color' => $colorService->getColorForMetric($tile['metric']),