Data Grid Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require bbit/data-grid-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       BranchBit\DataGridBundle\BranchBitDataGridBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Define a grid in a controller or service:

   use BranchBit\DataGridBundle\Grid\GridFactory;
   
   class MyController extends AbstractController
   {
       public function index(GridFactory $gridFactory)
       {
           $grid = $gridFactory->create([
               'data_source' => $this->getDoctrine()->getRepository(MyEntity::class)->findAll(),
               'columns' => [
                   'id' => 'ID',
                   'name' => 'Name',
               ],
           ]);
           return $this->render('my_template.html.twig', ['grid' => $grid]);
       }
   }
   

3. First Use Case Render a simple grid in Twig:

   {{ grid.render() }}
   

   This outputs a basic HTML table with pagination (if configured).

Implementation Patterns

Common Workflows

1. Dynamic Data Sources Use closures or services for dynamic data fetching:

   $grid = $gridFactory->create([
       'data_source' => function() {
           return $this->getDoctrine()->getRepository(MyEntity::class)
               ->createQueryBuilder('e')
               ->where('e.active = :active')
               ->setParameter('active', true)
               ->getQuery()
               ->getResult();
       },
       'columns' => [...],
   ]);
   

2. Column Customization Define column types (e.g., text, date, actions):

   'columns' => [
       'id' => ['type' => 'text', 'label' => 'ID'],
       'created_at' => ['type' => 'date', 'label' => 'Created At'],
       'actions' => [
           'type' => 'actions',
           'route' => 'app_edit',
           'route_parameters' => ['id' => 'id'],
           'buttons' => [
               ['label' => 'Edit', 'icon' => 'edit'],
               ['label' => 'Delete', 'icon' => 'delete'],
           ],
       ],
   ],
   

3. Pagination and Sorting Enable via configuration:

   $grid = $gridFactory->create([
       'data_source' => [...],
       'columns' => [...],
       'pagination' => ['page_size' => 20],
       'sortable_columns' => ['name', 'created_at'],
   ]);
   

4. Integration with Forms Use the form column type for inline editing:

   'columns' => [
       'name' => [
           'type' => 'form',
           'form_type' => 'text',
           'options' => ['attr' => ['class' => 'form-control']],
       ],
   ],
   

5. Event Listeners Attach listeners for pre/post-grid rendering:

   $grid->addPreRenderListener(function($grid) {
       $grid->addColumn('custom', 'Custom Column');
   });
   

Gotchas and Tips

Pitfalls

1. Outdated Codebase

   • Last release in 2017 may cause compatibility issues with modern Symfony/Laravel (e.g., Symfony 4/5/6, PHP 8.x).
   • Test thoroughly with your stack; expect deprecation warnings or breaking changes.

2. Limited Documentation

   • No official docs or examples beyond basic usage. Rely on:
     • Source code (read GridFactory, Grid, and Column classes).
     • Symfony’s DataGridBundle (this package is a fork; compare behaviors).

3. Doctrine Dependency

   • Assumes Doctrine ORM. For Eloquent (Laravel) or other databases, mock the Repository interface or adapt the data source.

4. Twig Integration

   • Twig templates may not work out-of-the-box with modern Symfony. Override templates in templates/BranchBitDataGrid/ or extend the base template.

5. Pagination Quirks

   • Pagination links may not respect your app’s routing. Customize the pagination_template or override the Pagination class.

Debugging Tips

1. Enable Debug Mode Add this to config/packages/branch_bit_data_grid.yaml (if supported):

   debug: true
   

   Check logs for grid events or data source issues.

2. Inspect the Grid Object Dump the grid object to verify configuration:

   dump($grid->getDataSource(), $grid->getColumns());
   

3. Override Templates Copy vendor/branchbit/data-grid-bundle/Resources/views/ to templates/BranchBitDataGrid/ to customize rendering without modifying the bundle.

Extension Points

1. Custom Column Types Extend BranchBit\DataGridBundle\Grid\Column\ColumnInterface to add new column types (e.g., select, checkbox).

2. Data Source Adapters Implement BranchBit\DataGridBundle\Grid\DataSourceInterface for non-Doctrine data sources (e.g., API clients, CSV files).

3. Event System Use GridEvents (e.g., PRE_RENDER, POST_RENDER) to modify grid behavior dynamically:

   $grid->addPostRenderListener(function($grid, $response) {
       $response->setContent($response->getContent() . '<div>Custom footer</div>');
   });
   

4. Configuration Overrides Override default settings in config/packages/branch_bit_data_grid.yaml:

   branch_bit_data_grid:
       default_page_size: 15
       default_sort_column: created_at
       default_sort_direction: desc
   

Laravel-Specific Notes

• Service Container Conflicts: The bundle uses Symfony’s DI. For Laravel, bind the GridFactory manually in a service provider:

  $this->app->bind('branchbit.data_grid.grid_factory', function($app) {
      return new \BranchBit\DataGridBundle\Grid\GridFactory();
  });
  

• Routing: Use Laravel’s routing system for action buttons. Override the actions column type to generate Laravel URLs:

  'actions' => [
      'type' => 'actions',
      'buttons' => [
          ['label' => 'View', 'route' => route('posts.show', ['post' => 'id'])],
      ],
  ],