Getting Started

Minimal Setup

Installation
```
composer require ajgl/jqgrid-bundle
```
Ensure ajgl/jqueryui-bundle (dependency) is also installed.

Enable the Bundle Add to config/bundles.php:

Ajgl\JqGridBundle\AjglJqGridBundle::class => ['all' => true],

Basic Usage Include the bundle’s assets in your base template (e.g., base.html.twig):
```
{{ ajgl_jqgrid_bundle_javascript() }}
{{ ajgl_jqgrid_bundle_stylesheets() }}
```

First Grid Example In a Twig template:

{{ ajgl_jqgrid({
    'id': 'grid',
    'url': path('api_data_source'),
    'datatype': 'json',
    'colModel': [
        { 'name': 'id', 'index': 'id', 'width': 55 },
        { 'name': 'name', 'index': 'name', 'width': 100 }
    ]
}) }}

API Endpoint Create a Symfony controller to return JSON data (e.g., src/Controller/DataController.php):

use Symfony\Component\HttpFoundation\JsonResponse;

public function getData(): JsonResponse
{
    $data = [
        ['id' => 1, 'name' => 'Item 1'],
        ['id' => 2, 'name' => 'Item 2']
    ];
    return new JsonResponse($data);
}

Implementation Patterns

Common Workflows

1. Dynamic Column Configuration

Use Twig logic to conditionally define columns:

{% set colModel = [] %}
{% for field in fields %}
    {% set colModel = colModel|merge([{
        'name': field.name,
        'index': field.name,
        'width': field.width|default(100),
        'editable': field.editable|default(false)
    }]) %}
{% endfor %}
{{ ajgl_jqgrid({ 'colModel': colModel }) }}

2. Server-Side Pagination/Sorting

Configure the grid to handle server-side operations:

{{ ajgl_jqgrid({
    'url': path('api_data'),
    'datatype': 'json',
    'page': 1,
    'rowNum': 20,
    'sortname': 'id',
    'sortorder': 'asc',
    'loadonce': false,  {# Disables client-side caching #}
    'viewrecords': true
}) }}

Controller Logic (e.g., src/Controller/DataController.php):

public function getData(Request $request): JsonResponse
{
    $page = $request->query->getInt('page', 1);
    $limit = $request->query->getInt('rows', 20);
    $sort = $request->query->get('sidx');
    $order = $request->query->get('sord');

    $data = $entityManager->getRepository(Entity::class)
        ->findWithPagination($page, $limit, $sort, $order);

    return new JsonResponse([
        'page' => $page,
        'total' => $data['totalPages'],
        'records' => $data['totalItems'],
        'rows' => $data['items']
    ]);
}

3. Inline Editing

Enable cell editing with editable: true and configure the editurl:

{{ ajgl_jqgrid({
    'colModel': [
        { 'name': 'id', 'index': 'id', 'editable': false },
        { 'name': 'name', 'index': 'name', 'editable': true }
    ],
    'editurl': path('api_edit_item'),
    'cellEdit': true,
    'cellsubmit': 'remote'
}) }}

Controller for Edits (src/Controller/DataController.php):

public function editItem(Request $request, EntityManagerInterface $em): JsonResponse
{
    $data = json_decode($request->getContent(), true);
    $entity = $em->getRepository(Entity::class)->find($data['id']);
    $entity->setName($data['name']);
    $em->flush();

    return new JsonResponse(['success' => true]);
}

4. Integration with Symfony Forms

Use the grid to render a form-backed dataset:

{{ form_start(form) }}
    {{ ajgl_jqgrid({
        'id': 'form_grid',
        'url': path('api_form_data'),
        'colModel': [
            { 'name': 'id', 'index': 'id', 'hidden': true },
            { 'name': 'name', 'index': 'name', 'editable': true }
        ],
        'editurl': path('api_edit_form_item'),
        'afterSaveCell': 'function() { $(this).trigger("reloadGrid"); }'
    }) }}
{{ form_end(form) }}

Integration Tips

Asset Management

The bundle registers JqGrid assets via ajgl_jqgrid_bundle_javascript() and ajgl_jqgrid_bundle_stylesheets(). Ensure these are included after jQuery and jQuery UI (if using themes).
For custom themes, override the bundle’s assets by copying files from vendor/ajgl/jqgrid-bundle/Resources/public/ to your project’s web/ directory.

Twig Extensions

The bundle provides ajgl_jqgrid() for rendering grids. For advanced use, access the underlying JqGridBuilder via:
```
{{ ajgl_jqgrid.getBuilder('grid_id').addOption('new_option', 'value') }}
```

Event Handling

Attach custom JavaScript events to the grid:

{{ ajgl_jqgrid({
    'id': 'grid',
    'onSelectRow': 'function(id) { alert("Selected: " + id); }',
    'loadComplete': 'function() { console.log("Grid loaded"); }'
}) }}

Gotchas and Tips

Pitfalls

1. Asset Loading Order

Issue: JqGrid fails to initialize if jQuery or jQuery UI is not loaded first.

Fix: Ensure the following order in your layout:

<!-- jQuery -->
{{ EncoreApp.bundle('app')|ignore_missing }}
<!-- jQuery UI (if using themes) -->
{{ ajgl_jqueryui_bundle_javascript() }}
<!-- JqGrid -->
{{ ajgl_jqgrid_bundle_javascript() }}

2. Deprecated Symfony 2.x

Issue: The bundle targets Symfony 2.x (requires symfony/framework-bundle:>=2.0,<2.2-dev). Compatibility with Symfony 3/4/5 is not guaranteed.
Fix: Use a fork or alternative bundle (e.g., FOSJsRoutingBundle + custom JqGrid integration) for modern Symfony.

3. Missing Documentation

Issue: The index.md in Resources/doc/ is minimal. Key features (e.g., advanced sorting, grouping) lack examples.
Fix:
- Refer to the official JqGrid docs.
- Inspect the bundle’s Tests/ directory for usage patterns.

4. CSRF Token for Edits

Issue: Inline edits via editurl may fail due to missing CSRF tokens.

Fix: Configure the grid to include tokens:

{{ ajgl_jqgrid({
    'editurl': path('api_edit_item', {
        '_token': app.request.csrfToken
    })
}) }}

Or use Symfony’s csrf_token() in JavaScript:

editurl: "{{ path('api_edit_item') }}?_token={{ csrf_token('edit_item') }}"

5. Memory Leaks with `loadonce: false`

Issue: Disabling loadonce can cause excessive server requests if pagination/sorting is misconfigured.
Fix: Validate server-side logic to handle page, rows, sidx, and sord parameters.

Debugging Tips

1. Console Errors

Check browser console for errors like:
- jqGrid not defined: Missing asset inclusion.
- 404 on editurl: Incorrect route or CSRF token.
Use {{ dump(ajgl_jqgrid.getBuilder('grid_id').getOptions()) }} to debug generated options.

2. Network Tab

Verify JSON responses match JqGrid’s expected format:
```
{
  "page": 1,
  "total": 1
```

Jqgrid Bundle Laravel Package