Grid Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require mmucklo/grid-bundle
   

   For Symfony 2/3, add new \Dtc\GridBundle\DtcGridBundle() to AppKernel.php.

2. Enable Reflection (Symfony 4+): Configure config/packages/dtc_grid.yaml:

   dtc_grid:
       reflection:
           allowed_entities: ['App:User', 'App:Product']  # Replace with your entities
   

3. Annotate an Entity:

   use Dtc\GridBundle\Annotation as Grid;
   
   

/**

• @Grid\Grid */ class User { ... }

4. Clear Cache:

   bin/console cache:clear
   bin/console cache:warmup
   

5. Access Grid: Visit /dtc_grid/grid?class=App:User&type=datatables (replace User with your entity).

First Use Case: Quick DataTable

Render a searchable, sortable table for App\Entity\User:

// In a controller
$renderer = $this->get('dtc_grid.renderer.factory')->create('datatables');
$gridSource = $this->get('dtc_grid.manager.source')->get('App:User');
$renderer->bind($gridSource);
return $this->render('@DtcGrid/Page/datatables.html.twig', $renderer->getParams());

Implementation Patterns

1. Annotation-Based Configuration

• Pros: Quick setup, declarative.
• Example:

  /**
   * @Grid\Grid(
   *     actions={
   *         @Grid\ShowAction(),
   *         @Grid\DeleteAction(),
   *         @Grid\Action(label="Custom", onclick="alert('Hello')")
   *     }
   * )
   */
  class User { ... }
  

2. YAML Configuration (Symfony 4+)

• File: config/dtc_grid/[entity].yaml
• Example:

  App\User:
    columns:
      username: { sortable: true, searchable: true }
      email: { searchable: true }
    actions:
      - { label: "Show", type: show, route: dtc_grid_show }
  

3. Dynamic Grid Rendering

• Use Case: Embed grids in custom routes.
• Example:

  /**
   * @Route("/custom-grid", name="custom_grid")
   */
  public function customGrid(Request $request) {
      $renderer = $this->get('dtc_grid.renderer.factory')->create('datatables');
      $gridSource = $this->get('dtc_grid.manager.source')->get('App:Product');
      $renderer->bind($gridSource);
      return $this->render('custom_grid.html.twig', $renderer->getParams());
  }
  

4. Multiple Grids on One Page

• Workflow:
  1. Fetch multiple gridSource instances.
  2. Render each with its own renderer.
  3. Pass all rendered grids to Twig.
• Example:

  {% for grid in grids %}
      {{ grid.render | raw }}
  {% endfor %}
  

5. Custom Column Logic

• Override Defaults:

  /**
   * @Grid\Column(
   *     label="Full Name",
   *     sortable=false,
   *     searchable=true,
   *     template="{{ entity.firstName }} {{ entity.lastName }}"
   * )
   */
  protected $fullName;
  

6. Integration with Forms

• Use Case: Edit rows inline.
• Pattern:
  • Use onclick actions to trigger modal forms.
  • Pass entity IDs via data-* attributes.
  • Example:

    @Grid\Action(
        label="Edit",
        onclick="openEditModal({{ entity.id }})",
        buttonClass="btn-primary"
    )
    

Gotchas and Tips

1. Cache Invalidation

• Issue: Changes to annotations/YAML require cache clearing.
• Fix:

  bin/console cache:clear
  bin/console cache:warmup
  

2. Reflection vs. YAML

• Gotcha: Reflection loads all allowed entities by default (performance hit).
• Tip: Use YAML for explicit control:

  dtc_grid:
      reflection:
          allowed_entities: ['App:CriticalEntity']  # Limit to essentials
  

3. Security

• Risk: Default /dtc_grid route is public.
• Fix: Restrict in security.yaml:

  access_control:
      - { path: ^/dtc_grid, roles: ROLE_ADMIN }
  

4. jQuery DataTables Quirks

• Issue: Custom CSS/JS paths may break if not absolute.
• Tip: Use CDN fallbacks or bundle assets:

  dtc_grid:
      datatables:
          js:
              - 'https://cdn.datatables.net/1.10.16/js/jquery.dataTables.min.js'
  

5. MongoDB ODM

• Gotcha: Field names must match Doctrine ODM mappings.
• Tip: Use odm_default in annotations:

  /**
   * @Grid\Column(odm_default="title")
   */
  protected $name;
  

6. Performance

• Issue: Large datasets slow down DataTables.
• Tips:
  • Use serverSide: true in DataTables config.
  • Limit columns with @Grid\Column annotations.
  • Paginate via datatables type:

    $renderer = $this->get('dtc_grid.renderer.factory')->create('datatables');
    

7. Custom Actions Debugging

• Issue: onclick actions fail silently.
• Tip: Log errors in Twig:

  <script>
      window.onload = function() {
          console.log("Grid loaded. Check browser console for errors.");
      };
  </script>
  

8. Twig Template Overrides

• Gotcha: Default templates may not match your theme.
• Tip: Override templates in templates/DtcGridBundle/:

  {# templates/DtcGridBundle/Page/datatables.html.twig #}
  {% extends "base.html.twig" %}
  {% block stylesheets %}
      {{ parent() }}
      {{ asset('css/custom-grid.css') }}
  {% endblock %}
  

9. Bootstrap Version Conflicts

• Issue: Bundle defaults to Bootstrap 3.
• Fix: Override in config/packages/dtc_grid.yaml:

  dtc_grid:
      bootstrap:
          css: 'https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/css/bootstrap.min.css'
  

10. Extension Points

• Custom Renderers: Extend \Dtc\GridBundle\Renderer\AbstractRenderer.
• Example:

  namespace App\Grid;
  use Dtc\GridBundle\Renderer\AbstractRenderer;
  
  class CustomRenderer extends AbstractRenderer {
      public function getType() { return 'custom'; }
      // Override render logic
  }
  

  Register as a service:

  services:
      app.grid.custom_renderer:
          class: App\Grid\CustomRenderer
          tags: { name: dtc_grid.renderer }
  

11. Debugging Grid Sources

• Tip: Dump gridSource to inspect columns/actions:

  $gridSource = $this->get('dtc_grid.manager.source')->get('App:User');
  dump($gridSource->getColumns());
  

12. Localization

• Issue: Default labels (e.g., "Actions") may not be translated.
• Tip: Override in Twig:

  {% trans with {'%column%': 'Aktionen'} %}Actions{% endtrans %}
  

  Or extend the bundle’s translation files.