Symfony DataTables Bundle

You can override the default automatic behavior of the ORMAdapter by providing custom query or criteria processors.

Custom Queries

Use the query option to provide a QueryBuilder processor. This is useful if you need specific joins or selections that the AutomaticQueryBuilder doesn't handle.

Custom Criteria

Use the criteria option to define how data is filtered. Note that providing your own criteria overrides the defaults (searching and sorting). To keep default searching, you must manually include SearchCriteriaProvider in your array of processors.

Events

You can listen to ORMAdapterEvents::PRE_QUERY to configure the QueryBuilder (e.g., enabling result or query caching) after it is built but before iteration starts.

// Custom Query
$table->createAdapter(ORMAdapter::class, [
    'entity' => Employee::class,
    'query' => function (QueryBuilder $builder) {
        $builder
            ->select('e')
            ->addSelect('c')
            ->from(Employee::class, 'e')
            ->leftJoin('e.company', 'c')
        ;
    },
]);

// Custom Criteria
$table->createAdapter(ORMAdapter::class, [
    'entity' => Employee::class,
    'criteria' => [
        function (QueryBuilder $builder) {
            $builder->andWhere($builder->expr()->like('c.name', ':test'))->setParameter('test', '%ny 2%');
        },
        new SearchCriteriaProvider(),
    ],
]);

// Event Listener
$table->addEventListener(ORMAdapterEvents::PRE_QUERY, function(ORMAdapterQueryEvent $event) {
    $event->getQuery()->useResultCache(true)->useQueryCache(true);
});

The bundle supports server-side exporting (Excel, CSV) to ensure all data can be exported even if it's not visible on the current client-side page.

Prerequisites:

• Install the DataTables Buttons extension.
• For Excel support, add phpoffice/phpspreadsheet to your project dependencies.

Server-side Configuration: You can customize the export behavior (like filename or file cleanup) using the DataTableExporterEvents::PRE_RESPONSE event.

Client-side Configuration: To trigger the export, use $.fn.initDataTables.exportBtnAction(exporterName, settings) within a DataTables button definition. Valid native exporters are excel and csv.

// Server-side: Customizing the export response
$table = $dataTableFactory->create()
    ->add(...)
    ->addEventListener(DataTableExporterEvents::PRE_RESPONSE, function (DataTableExporterResponseEvent $e) {
        $response = $e->getResponse();
        $response->deleteFileAfterSend(true);
        $ext = $response->getFile()->getExtension();
        $response->setContentDisposition(ResponseHeaderBag::DISPOSITION_ATTACHMENT, 'custom_filename.' . $ext);
    })
    ->handleRequest($request);

// Client-side: Adding an export button
$('#table').initDataTables({{ datatable_settings(datatable) }}, {
    dom:'<"html5buttons"B>lTfgitp',
    buttons: [
        {
            text: 'Export to Excel',
            action: $.fn.initDataTables.exportBtnAction('excel', {{ datatable_settings(datatable) }})
        }
    ]
});

If you have doctrine/orm and doctrine/doctrine-bundle installed, you can use the ORMAdapter to connect your DataTable to a Doctrine entity.

When using the ORMAdapter, you must provide the entity option with the full FQCN of the main entity. By default, the adapter uses an AutomaticQueryBuilder which recursively joins relationships to select only the fields defined by your columns. It also injects a default SearchCriteriaProvider for global searching.

To use a custom query or criteria, you can pass a single callable or an array of processors (callables or classes implementing QueryBuilderProcessorInterface) to the query or criteria options.

use Omines\
DataTablesBundle\\Adapter\\Doctrine\\ORMAdapter;

$table = $this->createDataTable()
    ->add('firstName', TextColumn::class)
    ->add('lastName', TextColumn::class)
    ->add('company', TextColumn::class, ['field' => 'company.name'])
    ->createAdapter(ORMAdapter::class, [
        'entity' => Employee::class,
    ]);

Global configuration is handled in your Symfony configuration files. Settings applied here will provide a uniform look and feel across all tables. Most settings can be overridden on individual tables using specific setter methods (e.g., setLanguageFromCDN(bool)).

Available Global Configuration Keys:

datatables:
    language_from_cdn: true
    method: POST
    options:
        option: value
    persist_state: fragment
    renderer: Omines\DataTablesBundle\Twig\TwigRenderer
    template: '@DataTables/datatable_html.html.twig'
    template_parameters:
        className: 'table table-bordered'
        columnFilter: null
    translation_domain: messages

To create a table, inject the DataTableFactory service into your controller. Use the create() method to instantiate a table, add() to define columns, and createAdapter() to bind a data source. The handleRequest() method manages AJAX callbacks. If the request is a callback, return the table's response directly; otherwise, render your template passing the table object.

Example using an ArrayAdapter with static data:

use Omines//... (truncated for brevity in record, but full logic below)
use Omines//... 
use Omines//... 
use Omines//... 

class MyController extends Controller
{
    public function showAction(Request $request, DataTableFactory $dataTableFactory)
    {
        $table = $dataTableFactory->create()
            ->add('firstName', TextColumn::class)
            ->add('lastName', TextColumn::class)
            ->createAdapter(ArrayAdapter::class, [
                ['firstName' => 'Donald', 'lastName' => 'Trump'],
                ['firstName' => 'Barack', 'lastName' => 'Obama'],
            ])
            ->handleRequest($request);
        
        if ($table->isCallback()) {
            return $table->getResponse();
        }
        
        return $this->render('list.html.twig', ['datatable' => $table]);
    }
}