Table Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ekyna/table-bundle:0.1.*@dev
   

   Add the bundle to app/AppKernel.php:

   new Ekyna\Bundle\TableBundle\EkynaTableBundle(),
   

2. First Table Type Create a table type class (e.g., src/Acme/DemoBundle/Table/Type/BrandType.php):

   use Ekyna\Component\Table\AbstractTableType;
   use Ekyna\Component\Table\TableBuilderInterface;
   
   class BrandType extends AbstractTableType {
       public function buildTable(TableBuilderInterface $tableBuilder) {
           $tableBuilder
               ->addColumn('id', 'number')
               ->addColumn('name', 'text');
       }
   }
   

3. Render the Table in a Controller

   use Ekyna\Bundle\TableBundle\Table\TableManager;
   
   class DemoController extends Controller {
       public function indexAction() {
           $table = $this->get('ekyna_table.manager')->createTable('brand', 'AcmeDemoBundle');
           return $this->render('AcmeDemo:Brand:index.html.twig', ['table' => $table]);
       }
   }
   

4. Twig Template

   {{ table.render() }}
   

Implementation Patterns

Core Workflows

1. Table Definition Extend AbstractTableType and implement buildTable() to define columns, filters, and sorting:

   $tableBuilder
       ->addColumn('field', 'type', ['options'])
       ->addFilter('field', 'filter_type')
       ->setDefaultSort('field', 'asc');
   

2. Dynamic Data Binding Use setData() in the controller to bind data to the table:

   $table->setData($entityManager->getRepository('AcmeDemoBundle:Brand')->findAll());
   

3. Customizing Rows Override configureRow() in your table type for per-row logic:

   public function configureRow($view, $rowData, $rowIndex) {
       $view->vars['custom_var'] = $rowData['name'] . '_custom';
   }
   

4. Pagination & Limits Configure via Twig or controller:

   {{ table.render({'limit': 10, 'page': request.query.page}) }}
   

5. Integration with Forms Use addActionColumn() to embed buttons/links:

   $tableBuilder->addActionColumn('actions', array(
       'route' => 'brand_edit',
       'routeParameters' => array('id' => 'id'),
       'label' => 'Edit',
   ));
   

Advanced Patterns

1. Reusable Table Types Create base table types for shared logic (e.g., AbstractUserTableType) and extend them.

2. Event Listeners Attach listeners to modify table behavior:

   $table->addListener(new CustomTableListener());
   

3. Custom Column Types Extend AbstractColumnType for specialized columns (e.g., DateColumnType).

4. AJAX Integration Use table.renderAsJson() for API responses:

   return new JsonResponse($table->renderAsJson());
   

5. Theming Override Twig templates in your bundle’s Resources/views/Table/ directory.

Gotchas and Tips

Common Pitfalls

1. Bundle Registration

   • Issue: Forgetting to register the bundle in AppKernel.php.
   • Fix: Ensure EkynaTableBundle is included in the $bundles array.

2. Namespace Conflicts

   • Issue: Using use Ekyna\Component\Table\TableBuilder instead of TableBuilderInterface.
   • Fix: Always use interfaces (TableBuilderInterface) for dependency injection.

3. Data Binding

   • Issue: setData() expects an array of objects with properties matching column names.
   • Fix: Use getters or normalize data:

     $table->setData(array_map(function($brand) {
         return (array) $brand;
     }, $brands));
     

4. Sorting/Filtering

   • Issue: Filters/sorting may fail if column names don’t match data keys.
   • Fix: Use addColumn('field', 'type', ['data_key' => 'actual_property']) for custom mappings.

5. Deprecated Methods

   • Issue: The package is outdated (last release 2015). Some methods may not exist.
   • Fix: Check the source code for available methods (e.g., TableBuilder may lack addFilter).

Debugging Tips

1. Enable Debug Mode Set ekyna_table.debug: true in config to log table building:

   ekyna_table:
       debug: true
   

2. Inspect Table Structure Dump the table object in the controller:

   dump($table->getDefinition());
   

3. Check Twig Variables Use {{ dump(table) }} in templates to verify passed data.

4. Override Templates Copy EkynaTableBundle:Table: templates to your bundle’s Resources/views/ to customize rendering.

Extension Points

1. Custom Column Types Extend Ekyna\Component\Table\Column\AbstractColumnType to add new column behaviors (e.g., BooleanColumnType).

2. Table Events Implement Ekyna\Component\Table\Event\TableEvents for pre/post-render hooks:

   $table->addListener(new class implements TableEvents {
       public function onPreRender(TableEvent $event) { ... }
   });
   

3. Filter Providers Create custom filter types by extending Ekyna\Component\Table\Filter\AbstractFilterType.

4. Configuration Overrides Use setDefaultOptions() to enforce bundle-wide settings:

   public function setDefaultOptions(OptionsResolverInterface $resolver) {
       $resolver->setDefaults([
           'default_limit' => 20,
           'paginate' => true,
       ]);
   }
   

5. Legacy Support For Symfony 2.x compatibility, ensure your composer.json targets the correct PHP version:

   "require": {
       "php": "5.3.3-7.1",
       "symfony/symfony": "2.3|2.7|2.8"
   }