Symgrid Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require arne-groskurth/symgrid
   

   Register the bundle in AppKernel.php:

   new ArneGroskurth\Symgrid\ArneGroskurthSymgridBundle(),
   new Bmatzner\FontAwesomeBundle\BmatznerFontAwesomeBundle()
   

   Run assets install:

   php app/console assets:install --symlink
   

2. Basic Usage in Controller:

   $grid = $this->get('arnegroskurth_symgrid.grid')
       ->from(User::class) // Entity data source
       ->useDefaultStyle();
   return $grid->getResponse('template.html.twig', ['grid' => $grid]);
   

3. Render in Twig:

   {{ symgrid(grid) }}
   

First Use Case: Quick Entity Grid

For a fast-start grid with Doctrine entities:

$grid = $this->get('arnegroskurth_symgrid.grid')
    ->from(User::class)
    ->useDefaultStyle()
    ->addColumn('id', 'ID', 'Numeric')
    ->addColumn('username', 'Username', 'String');

Implementation Patterns

Common Workflows

1. Data Source Integration

• Doctrine Entities (default):

  $grid->from(User::class);
  

• QueryBuilder:

  $qb = $this->getDoctrine()->getRepository(User::class)->createQueryBuilder('u');
  $grid->from($qb);
  

• Arrays:

  $grid->from([['id' => 1, 'name' => 'John'], ['id' => 2, 'name' => 'Jane']]);
  

2. Column Configuration

• Basic Columns:

  $grid->addColumn('id', 'ID', 'Numeric');
  $grid->addColumn('createdAt', 'Created At', 'DateTime');
  

• Custom Callbacks:

  $grid->addColumn('fullName', 'Full Name', 'String', [
      'callback' => function ($user) {
          return $user->getFirstName() . ' ' . $user->getLastName();
      }
  ]);
  

3. Filters and Aggregations

• Auto-Filters:

  $grid->enableAutoFilters();
  

• Custom Aggregations:

  $grid->addAggregation('total', 'Total Users', 'Count');
  

4. Actions

• Row Actions:

  $grid->addRowAction('edit', 'Edit', 'fa-pencil', '/user/edit/{id}');
  

• Mass Actions:

  $grid->addMassAction('delete', 'Delete Selected', 'fa-trash', '/user/delete');
  

5. Export

• CSV/Excel/PDF:

  $grid->enableExport(['csv', 'excel', 'pdf']);
  

6. Styling

• Default Style:

  $grid->useDefaultStyle();
  

• Custom CSS: Include in your layout:

  <link rel="stylesheet" href="{{ asset('bundles/arnegroskurthsymgrid/layout.css') }}" />
  <link rel="stylesheet" href="{{ asset('bundles/arnegroskurthsymgrid/style.css') }}" />
  

Gotchas and Tips

Pitfalls

1. Missing FontAwesomeBundle: Ensure Bmatzner\FontAwesomeBundle is registered; otherwise, icons (e.g., for actions) will break.

   new Bmatzner\FontAwesomeBundle\BmatznerFontAwesomeBundle()
   

2. Asset Installation: Forgetting assets:install will result in broken CSS/JS. Run:

   php app/console assets:install --symlink
   

3. Column Type Mismatches: Symgrid auto-detects column types, but explicit types (e.g., DateTime vs. Date) prevent rendering issues.

   $grid->addColumn('birthday', 'Birthday', 'Date'); // Explicit type
   

4. Pagination Conflicts: If using custom pagination, ensure the DataSource is configured to respect it:

   $grid->setPagination(10); // Default per-page items
   

5. Callback Performance: Avoid heavy logic in column callbacks; lazy-load data or use DQL expressions instead.

Debugging Tips

1. Check Grid Configuration: Use dump($grid->getConfiguration()) to verify settings before rendering.

2. Enable Debug Mode: Symgrid logs errors to Symfony’s logger. Check var/log/dev.log for issues.

3. JavaScript Errors: Clear cache (cache:clear) if JS events (e.g., filters) fail silently.

Extension Points

1. Custom Column Types: Extend ArneGroskurth\Symgrid\Grid\Column\Type\AbstractType to add new types (e.g., Email).

2. Override Templates: Copy Resources/views/ from the bundle to your project and modify (e.g., grid.html.twig).

3. Event Listeners: Register JS listeners for dynamic updates:

   $(document).on('symgrid:filter:change', function(e, grid, filters) {
       console.log('Filters changed:', filters);
   });
   

4. Translation Overrides: Extend translations in Resources/translations/ to customize labels/actions.

Performance Tips

1. Lazy-Load Data: Use QueryBuilder with pagination/fetch joins to avoid N+1 queries.

2. Disable Auto-Filters: If filters are rarely used:

   $grid->disableAutoFilters();
   

3. Cache Grid Config: For static grids, cache the configuration object to avoid re-parsing.