Datatablebundle Laravel Package

Getting Started

Minimal Steps

1. Installation Run:

   composer require dutchbridge/datatablebundle:dev-master
   

   Enable in AppKernel.php:

   new DutchBridge\DatatableBundle\DutchBridgeDatatableBundle(),
   

2. Bootstrap Setup Manually copy Bootstrap 2.3 assets (bootstrap.css, bootstrap.js, and icons) into:

   vendor/dutchbridge/datatablebundle/Resources/public/{css,js,img}
   

3. First Use Case Create a basic controller action to render a datatable for an entity (e.g., User):

   // src/AppBundle/Controller/UserController.php
   use DutchBridge\DatatableBundle\Datatable\View\DatatableView;
   use DutchBridge\DatatableBundle\Datatable\Doctrine\DoctrineDatatable;
   
   public function indexAction()
   {
       $datatable = new DoctrineDatatable($this->getDoctrine()->getManager(), 'AppBundle:User');
       $view = new DatatableView($datatable);
       return $this->render('AppBundle:User:index.html.twig', ['datatable' => $view]);
   }
   

4. Twig Template Use the provided Twig helpers in index.html.twig:

   {{ datatable.render() }}
   

Implementation Patterns

Core Workflows

1. Entity-Based Datatables

   • Instantiate DoctrineDatatable with an entity class (e.g., 'AppBundle:User').
   • Chain methods for filtering, sorting, and pagination:

     $datatable
         ->add('id', 'ID', null, ['searchable' => false])
         ->add('username', 'Username')
         ->add('email', 'Email')
         ->setDefaultSort(['username' => 'asc']);
     

2. Custom Columns

   • Add computed columns or use callbacks:

     $datatable->add('full_name', 'Full Name', function($user) {
         return $user->getFirstName() . ' ' . $user->getLastName();
     });
     

3. Server-Side Processing

   • Enable server-side filtering/sorting/pagination via setServerSide(true).
   • Override fetch() to customize queries:

     $datatable->setFetch(function($queryBuilder, $params) {
         // Custom logic (e.g., join tables, apply soft deletes)
         return $queryBuilder->getQuery()->getResult();
     });
     

4. Integration with Forms

   • Use datatable.form() in Twig to generate search forms:

     {{ form_start(datatable.form()) }}
         {{ form_widget(datatable.form.username) }}
         {{ form_widget(datatable.form.email) }}
     {{ form_end(datatable.form()) }}
     

5. AJAX Handling

   • Create a route for AJAX requests (e.g., /users/datatable):

     # app/config/routing.yml
     users_datatable:
         path:     /users/datatable
         defaults: { _controller: AppBundle:User:datatable }
     

   • Controller:

     public function datatableAction(Request $request)
     {
         $datatable = new DoctrineDatatable($this->getDoctrine()->getManager(), 'AppBundle:User');
         return $datatable->handleRequest($request)->render();
     }
     

Integration Tips

1. Asset Management

   • Enqueue Bootstrap assets in your base layout:

     {% block stylesheets %}
         {{ parent() }}
         {{ asset('bundles/dutchbridge/datatable/css/bootstrap.css') }}
     {% endblock %}
     

2. Styling

   • Override default styles by extending the bundle’s CSS:

     /* app/Resources/public/css/datatable_override.css */
     .dataTables_wrapper .dataTable {
         width: 100%;
     }
     

3. Laravel-Specific Adaptation

   • Replace Symfony’s Request with Laravel’s Illuminate\Http\Request in the bundle’s service container (if needed).
   • Use Laravel’s Doctrine bridge (e.g., laravel-doctrine/orm) for entity management.

4. Testing

   • Mock DoctrineDatatable in PHPUnit:

     $datatable = $this->getMockBuilder('DutchBridge\DatatableBundle\Datatable\Doctrine\DoctrineDatatable')
         ->disableOriginalConstructor()
         ->onlyMethods(['fetch'])
         ->getMock();
     

Gotchas and Tips

Pitfalls

1. Bootstrap Dependency

   • The bundle requires Bootstrap 2.3 (not 3/4/5). Mismatched versions may break styling.
   • Fix: Manually symlink or copy assets as described in the README.

2. Deprecated Symfony2 Features

   • The bundle assumes Symfony2 (e.g., Request object, Twig extensions). Laravel may need polyfills.
   • Tip: Use a compatibility layer like symfony/var-dumper for debugging.

3. No Laravel Service Provider

   • The bundle lacks Laravel-specific integration (e.g., no ServiceProvider or Facade).
   • Workaround: Manually bind the bundle’s services in config/app.php:

     'DutchBridge\DatatableBundle\DutchBridgeDatatableBundle' => DutchBridge\DatatableBundle\DutchBridgeDatatableBundle::class,
     

4. Limited Documentation

   • The README is sparse. Refer to the original fork for advanced usage.
   • Tip: Enable debug mode (APP_DEBUG=true) to inspect generated HTML/JS.

5. Performance with Large Datasets

   • Server-side processing (setServerSide(true)) can be slow for >10k records.
   • Optimization: Add database indexes or use DISTINCT in custom queries.

6. Twig Extension Conflicts

   • The bundle registers a datatable Twig function globally. Override in your app’s Twig config:

     // config/packages/twig.php
     twig:
         globals:
             datatable: '@dutchbridge.datatable.view'
     

Debugging Tips

1. Check Generated SQL Enable Doctrine logging in config/packages/dev/doctrine.php:

   doctrine:
       dbal:
           logging: true
           profiling: true
   

2. Inspect Request Data Dump the raw request payload in your AJAX handler:

   public function datatableAction(Request $request)
   {
       \Log::info('Datatable request:', $request->request->all());
       // ...
   }
   

3. Validate Column Definitions Ensure column names match entity fields (case-sensitive). Use:

   $metadata = $this->getDoctrine()->getManager()->getMetadataFactory()->getMetadataFor('AppBundle:User');
   $fieldNames = array_keys($metadata->fieldMappings);
   

Extension Points

1. Custom Datatable Classes Extend DoctrineDatatable to add entity-specific logic:

   class UserDatatable extends DoctrineDatatable
   {
       public function __construct(EntityManager $em)
       {
           parent::__construct($em, 'AppBundle:User');
           $this->add('roles', 'Roles', function($user) {
               return implode(', ', $user->getRoles());
           });
       }
   }
   

2. Override Twig Rendering Extend the DatatableView class to customize HTML output:

   class CustomDatatableView extends DatatableView
   {
       public function render()
       {
           // Inject custom templates or logic
           return $this->renderTemplate('AppBundle:Datatable:custom.html.twig');
       }
   }
   

3. Add Client-Side Features Extend the bundle’s JavaScript by overriding the datatable.js template:

   {{ datatable.render({
       'dom': '<"top"lf>rt<"bottom"ip>',
       'buttons': ['copy', 'csv']
   }) }}
   

4. Laravel Mix/Webpack Integration Process the bundle’s JS/CSS through Laravel Mix:

   // webpack.mix.js
   mix.copy('vendor/dutchbridge/datatablebundle/Resources/public/js', 'public/js/datatable');