Tabulator Bundle Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies Run composer require deviantlab/tabulator-bundle and ensure StimulusBundle is configured (required). If using Webpack Encore, execute npm install --force && npm run watch (or yarn equivalent).

2. Basic Configuration Add the bundle to config/bundles.php:

   return [
       // ...
       DeviantLab\TabulatorBundle\TabulatorBundle::class => ['all' => true],
   ];
   

3. First Use Case: Render a Table Use Twig to embed a Tabulator instance:

   {{ tabulator({
       'id': 'example-table',
       'data': dataSource,
       'columns': [
           { 'title': 'ID', 'field': 'id' },
           { 'title': 'Name', 'field': 'name' }
       ]
   }) }}
   

   • Data Source: Pass an array or use a controller to fetch data (e.g., Doctrine entities).
   • Stimulus Controller: The bundle auto-registers a tabulator controller; no manual JS required.

Implementation Patterns

Common Workflows

1. Dynamic Data Loading Fetch data via AJAX and update Tabulator:

   {{ tabulator({
       'id': 'dynamic-table',
       'data': [],
       'ajaxURL': path('api/data'),
       'ajaxConfig': { 'method': 'GET' }
   }) }}
   

   • Use Symfony’s path() helper for API routes.
   • Leverage Symfony’s JsonResponse for API endpoints.

2. Column Customization Define complex columns in Twig:

   {{ tabulator({
       'columns': [
           { 'title': 'Actions', 'formatter': 'button', 'formatterParams': { 'label': 'Edit' } },
           { 'title': 'Date', 'field': 'createdAt', 'formatter': 'datetime', 'formatterParams': { 'format': 'YYYY-MM-DD' } }
       ]
   }) }}
   

3. Integration with Forms Use Tabulator for form data binding:

   {{ form_row(form.field) }}
   {{ tabulator({
       'data': form.vars.data,
       'columns': [
           { 'field': 'id', 'editor': 'input' },
           { 'field': 'name', 'editor': 'input' }
       ]
   }) }}
   

   • Submit edits via Symfony’s form handling or custom JS events.

4. Reusable Components Create a base template for shared tables:

   {% macro tabulatorTable(id, data, columns) %}
       {{ tabulator({
           'id': id,
           'data': data,
           'columns': columns,
           'layout': 'fitColumns',
           'pagination': 'local',
           'paginationSize': 10
       }) }}
   {% endmacro %}
   

Integration Tips

• Symfony UX: Combine with SymfonyUx for reactive components (e.g., trigger reloads on form submission).
• Doctrine: Use DoctrineSerializer to convert entities to arrays for Tabulator:

  $data = $serializer->serialize($entities, 'json');
  

• Asset Management: Prefer AssetMapper over Webpack Encore for simpler setups (avoids npm run watch).

Gotchas and Tips

Pitfalls

1. Stimulus Dependency

   • Issue: Forgetting to install StimulusBundle causes silent failures.
   • Fix: Verify StimulusBundle is in bundles.php and assets are compiled.

2. Data Format Mismatch

   • Issue: Tabulator expects arrays with field keys matching column definitions.
   • Fix: Use ArrayTransformer or Serializer to normalize data:

     $transformedData = array_map(function ($item) {
         return ['id' => $item->getId(), 'name' => $item->getName()];
     }, $entities);
     

3. Asset Loading

   • Issue: Missing CSS/JS if Webpack Encore isn’t configured.
   • Fix: Run npm run build (or yarn build) after installation.

4. Twig Syntax Errors

   • Issue: Invalid JSON in Twig (e.g., unquoted keys).
   • Fix: Validate JSON with json_encode() in PHP or use {% set config = {...} %} for complex objects.

Debugging

• Console Logs: Check browser console for Stimulus/Tabulator errors (e.g., tabulator.min.js failures).
• Symfony Profiler: Use {{ dump(config) }} to inspect passed Tabulator options.

Extension Points

1. Custom Formatters Extend Tabulator’s formatters via JS:

   // assets/js/tabulator-extensions.js
   Tabulator.formatters.customFormatter = function(cell) {
       return `<span class="badge">${cell.getValue()}</span>`;
   };
   

   Register in Twig:

   {{ tabulator({
       'columns': [{ 'field': 'status', 'formatter': 'customFormatter' }]
   }) }}
   

2. Symfony Events Hook into Tabulator lifecycle via Stimulus events:

   {{ tabulator({
       'id': 'event-table',
       'data': data,
       'columns': columns,
       'onRowClick': 'function(e, row) { Stimulus.dispatch("tabulator-row-click", { detail: { row: row } }); }'
   }) }}
   

   Listen in a Stimulus controller:

   static get events() { return ['tabulator-row-click']; }
   

3. Configuration Overrides Override default settings in config/packages/deviantlab_tabulator.yaml:

   deviantlab_tabulator:
       default_options:
           layout: 'fitData'
           responsiveLayout: 'collapse'