Fancygrid Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your project via Composer:

   composer require cwd/fancygrid-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Cwd\FancyGridBundle\CwdFancyGridBundle::class => ['all' => true],
   ];
   

2. First Use Case: Basic Grid Configuration Define a grid in a controller or service:

   use Cwd\FancyGridBundle\Grid\Grid;
   use Cwd\FancyGridBundle\Grid\Column\Column;
   
   public function indexAction()
   {
       $grid = new Grid('my_grid_id');
       $grid->addColumn(new Column('id', 'ID', 'id'));
       $grid->addColumn(new Column('name', 'Name', 'name'));
   
       return $this->render('@CwdFancyGrid/Grid/grid.html.twig', [
           'grid' => $grid,
           'data' => $this->fetchData(), // Your data source
       ]);
   }
   

3. Twig Integration Ensure your template extends the base grid template:

   {% extends '@CwdFancyGrid/Grid/grid.html.twig' %}
   

Implementation Patterns

Common Workflows

1. Dynamic Column Configuration Use dependency injection to fetch columns dynamically:

   $grid->addColumn($this->columnFactory->create('dynamic_column'));
   

2. Data Source Integration

   • Doctrine ORM: Use Cwd\FancyGridBundle\Grid\DataProvider\DoctrineDataProvider.

     $grid->setDataProvider(new DoctrineDataProvider($entityManager, YourEntity::class));
     

   • Custom Data: Implement Cwd\FancyGridBundle\Grid\DataProvider\DataProviderInterface.

3. Event-Driven Customization Subscribe to grid events (e.g., GridEvents::PRE_BUILD) to modify behavior:

   $dispatcher->addListener(GridEvents::PRE_BUILD, function (GridEvent $event) {
       $event->getGrid()->addColumn(new Column('custom', 'Custom Column'));
   });
   

4. Reusable Grid Definitions Define grids as services for sharing across controllers:

   # config/services.yaml
   services:
       App\Grid\MyGrid:
           class: Cwd\FancyGridBundle\Grid\Grid
           arguments: ['my_grid_id']
           calls:
               - [addColumn, ['@App\Grid\Column\IdColumn']]
   

5. Pagination and Sorting Enable via configuration:

   $grid->setPagination(true)->setItemsPerPage(20);
   $grid->setSortableColumns(['id', 'name']);
   

Gotchas and Tips

Pitfalls

1. Caching Headaches

   • FancyGrid caches grid definitions aggressively. Clear cache after dynamic column additions:

     php bin/console cache:clear
     

   • Use unique grid IDs for dynamic grids to avoid conflicts.

2. Column Naming Collisions Ensure column IDs ($column->setId()) are unique within a grid. Overlapping IDs may cause rendering issues.

3. Data Provider Mismatches

   • Validate that your DataProvider returns data in the expected format (e.g., array of associative arrays).
   • Debug with var_dump($grid->getDataProvider()->getData()) if data is missing.

4. Twig Template Overrides

   • Avoid overriding @CwdFancyGrid/Grid/grid.html.twig directly. Extend it instead to preserve bundle updates:

     {% block fancygrid_body %}
         {{ parent() }}
         {{ include('your_custom_body.html.twig') }}
     {% endblock %}
     

Debugging Tips

1. Enable Debug Mode Set fancygrid.debug: true in config/packages/cwd_fancygrid.yaml to log grid events and SQL queries (if using Doctrine).

2. Check Grid Events Use Symfony’s event dispatcher to log grid builds:

   $dispatcher->addListener(GridEvents::PRE_BUILD, function (GridEvent $event) {
       error_log('Grid built: ' . $event->getGrid()->getId());
   });
   

3. Inspect Rendered HTML Use browser dev tools to verify column IDs and data attributes match your configuration.

Extension Points

1. Custom Column Types Extend Cwd\FancyGridBundle\Grid\Column\Column to add features like:

   • Conditional rendering:

     class ConditionalColumn extends Column {
         public function renderCell($value, $row) {
             return $value === 'active' ? '<span class="label label-success">Active</span>' : $value;
         }
     }
     

2. Custom Data Providers Implement DataProviderInterface for non-Doctrine sources (e.g., API clients):

   class ApiDataProvider implements DataProviderInterface {
       public function getData(Grid $grid) {
           return $this->apiClient->fetch($grid->getFilters());
       }
   }
   

3. Override Grid Templates Copy templates from vendor/cwd/fancygrid-bundle/Resources/views/ to templates/CwdFancyGrid/ to customize without forks.

4. Integrate with Symfony Forms Use Cwd\FancyGridBundle\Form\Type\GridType to bind grid configurations to forms:

   $builder->add('grid', GridType::class, [
       'grid' => $grid,
       'mapped' => false,
   ]);