Bsaggridbundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bs-code/bsaggridbundle
   

   Add to config/bundles.php:

   return [
       // ...
       BsCode\BsAgGridBundle\BsAgGridBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Publish the default config:

   php bin/console bs-ag-grid:install
   

   Edit config/packages/bs_ag_grid.yaml to define your data source (e.g., Doctrine entities).

3. First Use Case Create a Twig template (resources/views/aggrid/table.html.twig):

   {{ aggrid_table({
       'id': 'user-grid',
       'columns': [
           { 'field': 'id', 'headerName': 'ID' },
           { 'field': 'name', 'headerName': 'Name' }
       ],
       'rowData': path('bs_ag_grid_api_get_data', { entity: 'App\Entity\User' })
   }) }}
   

Implementation Patterns

Data Source Integration

• Doctrine ORM: Use bs_ag_grid.yaml to map entities:

  entities:
      App\Entity\User:
          fields:
              id: ~
              name: ~
          filters: [name]
  

• Custom Data Sources: Extend BsCode\BsAgGridBundle\DataSource\DataSourceInterface for non-Doctrine data (e.g., API calls, CSV).

API Endpoints

• Server-Side Processing: The bundle auto-generates routes like /api/bs-ag-grid/{entity}/data for pagination/filtering.
• Custom Logic: Override the controller via config/packages/bs_ag_grid.yaml:

  controllers:
      App\Entity\User: App\Controller\CustomUserGridController
  

Frontend Integration

• JavaScript Setup: Include AG Grid JS/CSS in your base template:

  <script src="https://unpkg.com/ag-grid-community/dist/ag-grid-community.min.js"></script>
  

• Dynamic Columns: Use Twig filters to generate columns dynamically:

  {% set columns = [] %}
  {% for field, config in aggrid_columns('App\Entity\User') %}
      {% set _ = columns.append(config) %}
  {% endfor %}
  

Workflows

1. CRUD Operations:
   • Use aggrid_table with editType: 'fullRow' for inline editing.
   • Bind to a form handler via onRowEditComplete.
2. Exporting:

   {{ aggrid_table({
       // ...,
       'enableExport': true,
       'exportTypes': ['csv', 'excel']
   }) }}
   

3. Real-Time Updates:
   • Poll the /api/bs-ag-grid/{entity}/data endpoint via JavaScript:

   setInterval(() => gridApi.getServerSideDatasource().refresh(), 30000);
   

Gotchas and Tips

Debugging

• API Issues: Check var/log/dev.log for Doctrine/QueryBuilder errors. Enable SQL logging in config/packages/doctrine.yaml:

  dbal:
      logging: true
  

• Frontend Errors: Use AG Grid’s onGridReady to log errors:

  onGridReady: (params) => {
      params.api.addEventListener('modelUpdated', () => {
          console.log('Grid state:', params.api.getModel());
      });
  }
  

Configuration Quirks

• Field Mapping: Ensure fields in bs_ag_grid.yaml match the entity properties exactly (case-sensitive).
• Pagination: Defaults to 10 rows/page. Override via:

  default_pagination_page_size: 25
  

• Caching: Clear the cache after changing bs_ag_grid.yaml:

  php bin/console cache:clear
  

Extension Points

• Custom Filters: Extend BsCode\BsAgGridBundle\Filter\FilterInterface and register in services.yaml:

  services:
      App\Filter\CustomFilter:
          tags: [bs_ag_grid.filter]
  

• Column Types: Override default column types by creating a BsAgGridBundle service:

  services:
      BsCode\BsAgGridBundle\Column\ColumnType\TextColumnType:
          arguments:
              $cellRenderer: 'customRenderer'
  

• Security: Restrict grid access via Symfony voters or firewall rules. Example voter:

  // src/Voter/GridAccessVoter.php
  public function supports(string $attribute, $subject): bool
  {
      return $attribute === 'GRID_ACCESS' && $subject instanceof UserInterface;
  }
  

Performance

• Lazy Loading: For large datasets, use serverSideStoreType: 'serverSide' in config.
• Selective Field Loading: Fetch only required fields in Doctrine queries:

  entities:
      App\Entity\Product:
          fields:
              id: ~
              name: ~
          dql_partition: 'p.id IN (:ids)'  # Custom DQL for IDs