Ux Datatable Laravel Package

Getting Started

Minimal Setup

1. Prerequisites:

   • Ensure Symfony UX is configured (symfony/ux installed and Stimulus bridge ≥3.0).
   • Install the package:

     composer require aziz403/ux-datatable
     npm install --force && npm run watch
     

2. First Use Case:

   • Entity Datatable (most common):

     // src/Controller/PostController.php
     use Aziz403\UX\Datatable\Builder\DatatableBuilderInterface;
     use Symfony\UX\Datatable\Model\EntityDatatable;
     use App\Entity\Post;
     
     #[Route('/posts', name: 'posts')]
     public function index(Request $request, DatatableBuilderInterface $builder): Response
     {
         $datatable = $builder->createDatatableFromEntity(Post::class)
             ->add('id', 'TextColumn')
             ->add('title', 'TextColumn')
             ->add('createdAt', 'DateColumn');
     
         $datatable->handleRequest($request);
         return $this->render('posts/index.html.twig', [
             'datatable' => $datatable,
         ]);
     }
     

   • Render in Twig:

     {{ render_datatable(datatable) }}
     

Implementation Patterns

1. Entity Datatables (Recommended for CRUD)

• Workflow:

  1. Define Columns:

     $datatable
         ->add('id', TextColumn::class)
         ->add('name', TextColumn::class)
         ->add('isActive', BooleanColumn::class)
         ->add('actions', TwigColumn::class, [
             'template' => 'posts/_actions.html.twig',
         ]);
     

  2. Handle Request:

     $datatable->handleRequest($request);
     if ($datatable->isSubmitted()) {
         return $datatable->getResponse(); // AJAX response
     }
     

  3. Render:

     {{ render_datatable(datatable) }}
     

• Integration Tips:

  • Use EntityColumn for relationships:

    ->add('category', EntityColumn::class, ['entity' => Category::class, 'property' => 'name'])
    

  • Sorting/Filtering: Enable server-side processing (default) for large datasets:

    $datatable->setServerSide(true);
    

2. Array Datatables (Static Data)

• Use Case: Display non-entity data (e.g., API responses, form submissions).
• Example:

  $data = [
      ['id' => 1, 'name' => 'Item 1'],
      ['id' => 2, 'name' => 'Item 2'],
  ];
  $datatable = $builder->createDatatableFromArray(
      [
          new TextColumn('id'),
          new TextColumn('name'),
      ],
      $data
  );
  

3. Global Customization

• Stimulus Controller: Extend functionality via Stimulus (e.g., global search, custom buttons):

  // assets/controllers/my_datatable_controller.js
  import { Controller } from '@hotwired/stimulus';
  
  export default class extends Controller {
      connect() {
          this.element.addEventListener('datatable:connect', (e) => {
              e.detail.table.button().add(0, {
                  text: 'Export',
                  action: () => alert('Export clicked!')
              });
          });
      }
  }
  

  Register in config/packages/datatable.yaml:

  datatable:
      global_controller: 'my_datatable'
  

• Configuration:

  • Theme: Set in config/packages/datatable.yaml:

    datatable:
        template_parameters:
            style: 'bootstrap5'
    

  • Language: Override defaults (e.g., for French):

    datatable:
        language: 'fr'
        language_from_cdn: false
    

4. Events & Filters

• Modify Queries: Use events to alter data fetching:

  // src/EventListener/CustomFilterListener.php
  use Aziz403\UX\Datatable\RenderSearchQueryEvent;
  
  public function onSearchQuery(RenderSearchQueryEvent $event) {
      $event->getQuery()->andWhere('entity.isActive = :active')
          ->setParameter('active', true);
  }
  

  Register in services.yaml:

  services:
      App\EventListener\CustomFilterListener:
          tags:
              - { name: kernel.event_listener, event: datatable.search_query }
  

• Dynamic Filters: Add runtime filters:

  $datatable->addFilter(function (RenderSearchQueryEvent $event) {
      $event->getQuery()->andWhere('entity.name LIKE :name')
          ->setParameter('name', '%' . $event->getRequest()->query->get('search') . '%');
  });
  

Gotchas and Tips

Pitfalls

1. Missing Translations:

   • If language_from_cdn: false, ensure all required translation keys (e.g., datatable.datatable.search) exist in your translation files.
   • Fix: Run symfony local:messages en to generate missing keys.

2. Server-Side Processing:

   • Forgetting handleRequest() or isSubmitted() checks will break AJAX responses.
   • Fix: Always include:

     $datatable->handleRequest($request);
     if ($datatable->isSubmitted()) {
         return $datatable->getResponse();
     }
     

3. Stimulus Controller Conflicts:

   • Multiple Stimulus controllers on the same element may cause issues.
   • Fix: Use unique controller names and clean up listeners in disconnect().

4. Column Type Mismatches:

   • Using TextColumn for a DateTime field without conversion will render raw data.
   • Fix: Use DateColumn or TwigColumn for custom formatting.

Debugging Tips

1. Check AJAX Responses:

   • Inspect network requests in DevTools to verify payloads (e.g., draw, columns, order).
   • Common Issues:
     • Missing draw parameter → Server returns full dataset instead of paginated results.
     • Incorrect columns array → Columns may not align with data.

2. Log Queries:

   • Enable Doctrine logging to debug query generation:

     # config/packages/dev/doctrine.yaml
     doctrine:
         dbal:
             logging: true
             profiling: true
     

3. Stimulus Events:

   • Use console.log in Stimulus controllers to debug event payloads:

     _onConnect(event) {
         console.log('Datatable options:', event.detail.options);
     }
     

Extension Points

1. Custom Columns:

   • Extend AbstractColumn for reusable column types:

     // src/Column/CustomColumn.php
     use Aziz403\UX\Datatable\Column\AbstractColumn;
     
     class CustomColumn extends AbstractColumn {
         public function getValue($entity, $datatable) {
             return $entity->getCustomProperty() . ' (custom)';
         }
     }
     

2. Override Templates:

   • Customize the Twig template for render_datatable:

     {# templates/datatable.html.twig #}
     <div class="custom-datatable">
         {{ parent() }} {# Include parent template #}
     </div>
     

   • Override in config/packages/datatable.yaml:

     datatable:
         template: 'datatable.html.twig'
     

3. Performance:

   • Lazy Loading: Use ->setServerSide(true) for large datasets (>1000 rows).
   • Selective Columns: Only fetch columns needed for display:

     $datatable->setColumns(['id', 'name']); // Explicitly set columns
     

4. Security:

   • CSRF Protection: Ensure AJAX routes use Symfony’s CSRF token system.
   • Input Validation: Sanitize dynamic filters to prevent SQL injection:

     $searchTerm = $event->getRequest()->query->get('search', '');
     $event->getQuery()->andWhere('entity.name LIKE :name')
         ->setParameter('name', '%' . addslashes($searchTerm) . '%');