Bootgrid Bundle Laravel Package

Getting Started

Minimal Setup

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

   composer require cwd/bootgrid-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       CWD\BootgridBundle\CWDBootgridBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Define a route and template for your first grid:

   # config/packages/cwd_bootgrid.yaml
   cwd_bootgrid:
       templates:
           default: 'BootgridBundle::default.html.twig'
   

3. First Use Case Create a controller to render a grid:

   // src/Controller/ExampleController.php
   use CWD\BootgridBundle\Grid\Grid;
   use CWD\BootgridBundle\Grid\Source\ArraySource;
   
   class ExampleController extends AbstractController
   {
       public function gridAction()
       {
           $grid = new Grid();
           $grid->setSource(new ArraySource([
               ['id' => 1, 'name' => 'Item 1'],
               ['id' => 2, 'name' => 'Item 2'],
           ]));
           $grid->setColumns([
               'id', 'name'
           ]);
   
           return $this->render('example/grid.html.twig', [
               'grid' => $grid,
           ]);
       }
   }
   

4. Template Integration Use the provided Twig template:

   {% extends 'BootgridBundle::default.html.twig' %}
   
   {% block grid %}
       {{ grid|bootgrid }}
   {% endblock %}
   

Implementation Patterns

Data Sources

• ArraySource: For static data (as shown above).
• DoctrineSource: For database queries (requires doctrine/orm):

  $grid->setSource(new DoctrineSource(
      $entityManager->getRepository(Entity::class)->findAll()
  ));
  

• Custom Sources: Implement CWD\BootgridBundle\Grid\Source\SourceInterface.

Column Configuration

Define columns with options:

$grid->setColumns([
    'id' => [
        'title' => 'ID',
        'sortable' => true,
        'formatter' => 'html',
    ],
    'name' => [
        'title' => 'Name',
        'width' => '200px',
    ],
]);

Pagination & Sorting

Enable via configuration:

$grid->setDefaultSort('id');
$grid->setPaging(true);
$grid->setPagingOptions(['pageSize' => 10, 'pageSizes' => [5, 10, 20]]);

Client-Side Features

Leverage Bootgrid’s JS features (e.g., filtering, row selection) by extending the template:

{% block grid_options %}
    {{ parent() }}
    {{
        grid|bootgrid_options({
            'selection': true,
            'multiSelect': true,
            'rowSelect': true
        })
    }}
{% endblock %}

Integration with Forms

Bind grid selections to Symfony forms:

$form = $this->createFormBuilder()
    ->add('selectedItems', HiddenType::class)
    ->getForm();

// In Twig:
{{ form_widget(form) }}
<script>
    $('#grid').on('loaded.rs.jquery.bootgrid', function() {
        $('#grid').bootgrid('getSelectedRows').then(function(rows) {
            $('#example_controller_selectedItems').val(JSON.stringify(rows));
        });
    });
</script>

Gotchas and Tips

Pitfalls

1. Twig Template Overrides

   • If extending templates, ensure {% block grid %} and {% block grid_options %} are preserved.
   • Clear cache after template changes:

     php bin/console cache:clear
     

2. DoctrineSource Caching

   • Avoid caching DoctrineSource queries if data changes frequently. Use setCacheLifetime(0) if needed.

3. JavaScript Conflicts

   • Bootgrid relies on jQuery. Ensure it’s loaded before the bundle’s JS:

     {{ parent() }} {# Loads jQuery if missing #}
     {{ cwd_bootgrid_js() }}
     

4. CSRF in AJAX Requests

   • For server-side operations (e.g., row deletion), include CSRF tokens:

     {% block grid_toolbar %}
         {{ form_start(form, {'attr': {'id': 'delete-form'}}) }}
             {{ form_widget(form.delete) }}
         {{ form_end(form) }}
     {% endblock %}
     

Debugging Tips

• Check Console for Errors: Bootgrid logs JS errors to the console. Look for Uncaught TypeError or 404 requests.
• Inspect Network Requests: Verify AJAX calls (pagination/sorting) return valid JSON:

  {
      "rows": [...],
      "total": 100
  }
  

• Disable Caching Temporarily: Add ?nocache=1 to URLs during development.

Extension Points

1. Custom Formatters Add a Twig formatter (e.g., src/Twig/Extension/BootgridExtension.php):

   public function getFormatter($value, $column)
   {
       if ($column['formatter'] === 'custom') {
           return '<span class="badge">'.$value.'</span>';
       }
       return $value;
   }
   

2. Event Listeners Subscribe to grid events (e.g., row selection):

   $grid->on('rowSelected', function($event) {
       $row = $event->getRow();
       // Handle selection
   });
   

3. Override Default Templates Copy vendor/cwd/bootgrid-bundle/Resources/views/ to templates/cwd_bootgrid/ and customize.

Performance

• Lazy Loading: Use setLazyLoading(true) for large datasets.
• Server-Side Processing: Offload filtering/sorting to the database:

  $grid->setSource(new DoctrineSource(
      $entityManager->getRepository(Entity::class)->createQueryBuilder('e')
          ->getQuery()
  ));