Table Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require araise/table-bundle
   yarn add tailwindcss postcss-loader sass-loader sass autoprefixer --dev
   

   Configure tailwind.config.js and webpack.config.js as per the docs.

2. Basic Setup:

   • Ensure default_locale in config/packages/framework.yaml is set to de for German translations (optional).
   • Extend your base template with:

     {% block stylesheets %}
         {{ parent() }}
         @import "~@araise/table-bundle/styles/_tailwind.scss";
     {% endblock %}
     

3. First Table: Create a controller with a Doctrine-backed table:

   #[Route('/', name: 'index')]
   public function index(TableFactory $tableFactory, PostRepository $postRepository): Response
   {
       $table = $tableFactory->create('posts', null, [
           'dataloader_options' => [
               DoctrineDataLoader::OPT_QUERY_BUILDER => $postRepository->createQueryBuilder('post'),
           ],
       ]);
       $table
           ->addColumn('title')
           ->addColumn('description')
           ->addAction('detail', [
               'route' => 'detail',
               'route_parameters' => fn($post) => ['id' => $post->getId()],
           ]);
       return $this->render('index.html.twig', ['table' => $table]);
   }
   

   Render in Twig:

   {{ araise_table_render(table) }}
   

Implementation Patterns

Core Workflows

1. Data Loading:

   • Doctrine: Use DoctrineDataLoader for database-backed tables (default).

     $tableFactory->create('posts', null, [
         'dataloader_options' => [
             DoctrineDataLoader::OPT_QUERY_BUILDER => $repo->createQueryBuilder('p'),
         ],
     ]);
     

   • Arrays: Use ArrayDataLoader for static data:

     $tableFactory->create('projects', ArrayDataLoader::class, [
         'dataloader_options' => [ArrayDataLoader::OPT_DATA => $arrayData],
     ]);
     

2. Column Configuration:

   • Basic columns:

     $table->addColumn('title'); // Auto-detects accessor
     $table->addColumn('description', 'Beschreibung'); // Custom label
     

   • Custom accessors (for arrays/objects):

     $table->addColumn('Name', null, ['accessor_path' => '[name]']);
     

   • Formatted columns:

     $table->addColumn('email', 'E-Mail', ['formatter' => 'email']);
     

3. Actions:

   • Route-based actions:

     $table->addAction('edit', [
         'label' => 'Bearbeiten',
         'route' => 'edit_post',
         'route_parameters' => fn($post) => ['id' => $post->getId()],
     ]);
     

   • JavaScript actions:

     $table->addAction('delete', [
         'label' => 'Löschen',
         'js' => 'confirmDelete(this)',
     ]);
     

4. Filters:

   • Add filters via FilterExtension:

     $table->getFilterExtension()
         ->addFilterType('status', 'Status', ChoiceFilterType::class, [
             ChoiceFilterType::OPT_CHOICES => ['draft', 'published'],
         ]);
     

   • Predefined filters:

     $table->getFilterExtension()
         ->predefineFilter('featured', 'published', TextFilterType::CRITERIA_EQUAL, 'published')
         ->and('author', TextFilterType::CRITERIA_CONTAINS, 'John');
     

5. Pagination:

   • Configure via table options:

     $tableFactory->create('posts', null, [
         'pagination' => [
             'page_size' => 20,
             'page_parameter' => 'page',
         ],
     ]);
     

Integration Tips

• Twig Extensions: Use araise_table_render (full) or araise_table_only_render (no pagination/filters).
• Turbo Integration: Enable via config (araise_table.enable_turbo: true) for SPA-like behavior.
• Custom Formatters: Register formatters as services with the core.formatter tag:

  services:
      App\Formatter\CustomFormatter:
          tags: ['core.formatter']
  

• CSS Overrides: Extend Tailwind classes in your app.scss:

  @layer components {
      .araise-table {
          &__cell { @apply py-2; }
      }
  }
  

Gotchas and Tips

Pitfalls

1. Tailwind Configuration:

   • Missing Colors: Forgetting to define primary and error colors in tailwind.config.js will break the bundle’s styles.
   • Content Paths: Ensure ./vendor/araise/**/*.{html,html.twig,js} is included in content in tailwind.config.js.
   • Order Matters: Araise styles must be imported after @tailwind directives in app.scss.

2. DataLoader Quirks:

   • Doctrine Joins: Complex joins may require explicit OPT_JOINS in filter configurations:

     $table->getFilterExtension()->addFilterType('city', 'City', ChoiceFilterType::class, [
         FilterType::OPT_JOINS => ['c' => 'p.address.city'],
     ]);
     

   • ArrayDataLoader: Accessor paths must use array notation ([key]) for nested arrays.

3. Filter Issues:

   • Case Sensitivity: Filter criteria like CRITERIA_EQUAL are case-sensitive unless configured otherwise.
   • Ajax Filters: Ensure OPT_JSON_SEARCH_URL routes are properly defined and accessible.

4. Performance:

   • Large Datasets: Paginate early in DoctrineDataLoader to avoid memory issues:

     $qb->setFirstResult(($page - 1) * $pageSize)->setMaxResults($pageSize);
     

   • Eager Loading: Use OPT_JOINS to fetch related data upfront and avoid N+1 queries.

5. Translation:

   • Missing Translations: Only German is provided by default. Override labels or submit PRs for new locales.

Debugging Tips

1. Table Dump: Use dump($table->getConfiguration()) to inspect the table’s internal state (columns, filters, etc.).

2. Query Debugging: Enable Doctrine’s query logging in config/packages/dev/doctrine.yaml:

   doctrine:
       dbal:
           logging: true
           profiling: true
   

3. Filter Debugging:

   • Check the FilterExtension for applied filters:

     dump($table->getFilterExtension()->getAppliedFilters());
     

   • Validate OPT_COLUMN paths match your entity structure.

4. Turbo Conflicts:

   • If Turbo (Hotwire) behaves unexpectedly, disable it temporarily via config:

     araise_table:
         enable_turbo: false
     

Extension Points

1. Custom Filter Types: Extend araise\TableBundle\Filter\Type\AbstractFilterType and register as a service:

   class CustomFilterType extends AbstractFilterType {
       public function apply(QueryBuilder $qb, $value, string $alias, string $column): void {
           // Custom logic
       }
   }
   

   Tag the service:

   services:
       App\Filter\CustomFilterType:
           tags: ['araise.table.filter_type']
   

2. Custom DataLoaders: Implement araise\TableBundle\DataLoader\DataLoaderInterface for non-Doctrine/array sources (e.g., API calls).

3. Twig Overrides: Override templates by copying from vendor/araise/table-bundle/resources/views/ to templates/bundles/araise/table/.

4. Formatter Extensions: Create custom formatters for complex data (e.g., dates, enums):

   class DateFormatter extends AbstractFormatter {
       public static function getString($value): string {
           return (new \DateTime($value))->format('d.m.Y');
       }
   }
   

   Register and use:

   $table->addColumn('created_at', null, ['formatter' => 'date']);