Getting Started

Minimal Steps

Installation:

composer require customscripts/datagrid-bundle:dev-master

new CS\DataGridBundle\CSDataGridBundle(),

First Use Case: Define a basic grid configuration in a controller or service:

use CS\DataGridBundle\Grid\Grid;

$grid = new Grid();
$grid->setDataSource('doctrine', ['entity' => 'AppBundle:User']);
$grid->setColumns(['id', 'username', 'email']);
$grid->setPageSize(10);

Render the Grid: Pass the grid to a Twig template:

{{ render(controller('CSDataGridBundle:Grid:render', {'grid': grid})) }}

Where to Look First

Documentation: Check the src/CS/DataGridBundle/ directory for core classes (Grid, Column, DataSource).
Examples: Look for Resources/views/ in the bundle (if any) or test cases for usage patterns.
Configuration: Review Resources/config/services.yml for bundle services and dependencies.

Implementation Patterns

Core Workflows

Grid Definition:

Use the Grid class to define structure:

$grid = new Grid();
$grid->setDataSource('doctrine', ['entity' => 'AppBundle:User']);
$grid->setColumns([
    'id' => ['label' => 'ID', 'type' => 'number'],
    'username' => ['label' => 'Username', 'type' => 'text'],
]);

Data Sources:

Doctrine QueryBuilder:

$grid->setDataSource('doctrine', [
    'entity' => 'AppBundle:User',
    'query' => function($qb) {
        $qb->where('u.active = 1');
    }
]);

Array Data:

$grid->setDataSource('array', ['data' => $arrayData]);

Pagination:

Enable via setPageSize() and handle pagination in the template:

{% for row in grid.rows %}
    {{ row.id }} - {{ row.username }}
{% endfor %}
{{ grid.pagination }}

Filters and Search:

Add filters dynamically:

$grid->addFilter('username', 'text', 'Contains');
$grid->setSearchField('username');

Actions:

Define row actions (e.g., edit/delete):

$grid->addAction('edit', ['route' => 'user_edit', 'params' => ['id' => 'id']]);

Integration Tips

Twig Integration: Use the render Twig function or pass the grid object to a custom template:
```
{% for column in grid.columns %}
    <th>{{ column.label }}</th>
{% endfor %}
```

Event Listeners: Extend functionality via events (if supported):

$grid->addListener('preRender', function($event) {
    $event->getGrid()->addColumn('custom', ['label' => 'Custom Field']);
});

Dependency Injection: Register grid services in services.yml for reuse:

services:
    app.user_grid:
        class: CS\DataGridBundle\Grid\Grid
        calls:
            - [setDataSource, ['doctrine', { entity: 'AppBundle:User' }]]

Gotchas and Tips

Pitfalls

Symfony 2.1 Dependency:
- The bundle only works with Symfony 2.1. Attempting to use it in newer versions (e.g., 2.3+) may break due to API changes.
- Workaround: Fork the bundle and update dependencies if migrating to a newer Symfony version.
Limited Documentation:
- The README is incomplete (e.g., "Creating your first Grid" is marked "Coming Soon").
- Tip: Inspect the src/ directory for undocumented features or check the Grid class for available methods.
Data Source Quirks:
- Doctrine data sources may require explicit QueryBuilder setup. Test with simple queries first.
- Array data sources assume a flat structure. Nested data may need preprocessing.
Pagination Conflicts:
- If using custom pagination logic, ensure the bundle’s pagination parameters (page, pageSize) align with your template.
Action Routing:
- Action routes (e.g., edit) assume standard Symfony routing. Custom route names may require manual parameter passing:
```
$grid->addAction('edit', ['route' => 'app.user_edit', 'params' => ['id' => 'id']]);
```

Debugging Tips

Check Grid Configuration:
- Dump the grid object before rendering to verify settings:
```
dump($grid->getColumns(), $grid->getDataSource());
```
Enable Debug Mode:
- Symfony’s debug toolbar can help identify missing templates or routing issues.

Log Data Sources:

For Doctrine queries, log the generated SQL:

$grid->setDataSource('doctrine', [
    'entity' => 'AppBundle:User',
    'query' => function($qb) {
        $qb->where('u.active = 1');
        return $qb->getQuery()->getSQL(); // Log this for debugging
    }
]);

Extension Points

Custom Columns:

Extend the Column class to add custom types (e.g., date, boolean):

class CustomColumn extends \CS\DataGridBundle\Grid\Column {
    public function render($value) {
        return $value ? 'Yes' : 'No';
    }
}

Data Source Plugins:

Implement a new data source by extending AbstractDataSource:

class ApiDataSource extends AbstractDataSource {
    public function fetch() {
        return $this->httpClient->request('GET', '/api/users')->toArray();
    }
}

Twig Extensions:

Create a custom Twig function to render grids with additional logic:

$twig->addFunction(new \Twig_SimpleFunction('custom_grid', function($grid) {
    // Preprocess grid data
    return $grid->render();
}));

Event-Driven Extensions:
- If the bundle supports events (e.g., preRender, postRender), hook into them for dynamic modifications:
```
$grid->addListener('preRender', function($event) {
    $event->getGrid()->addColumn('status', ['label' => 'Status']);
});
```

Configuration Quirks

Bundle Prefix: The bundle uses CSDataGridBundle as the namespace prefix. Ensure your templates and services reflect this (e.g., CS\DataGridBundle\Grid\Grid).
Template Overrides: Override default templates by copying them from vendor/customscripts/datagrid-bundle/Resources/views/ to app/Resources/CSDataGridBundle/views/.
Caching: If performance is critical, cache grid configurations or data sources manually, as the bundle may not include built-in caching.

Datagrid Bundle Laravel Package