---
title: "Developer"
manual: "Calien - XLS Exporter"
version: "5.1"
permalink: "https://docs.typo3.org/permalink/calien/xlsexport:developer@5.1"
source: "Developer/Index.rst"
rendered: "2026-11-19T10:49:27+00:00"
---

# Developer {#developer}

**Table of contents**

-   [Filtering exports](https://docs.typo3.org/permalink/calien/xlsexport:filtering-exports@5.1)
-   [ModifyExportModuleViewEvent](https://docs.typo3.org/permalink/calien/xlsexport:modifyexportmoduleviewevent@5.1)
-   [ModifyExportCountQueryEvent](https://docs.typo3.org/permalink/calien/xlsexport:modifyexportcountqueryevent@5.1)
-   [ModifyExportQueryEvent](https://docs.typo3.org/permalink/calien/xlsexport:modifyexportqueryevent@5.1)
-   [AlternateFirstColumnInSheetEvent](https://docs.typo3.org/permalink/calien/xlsexport:alternatefirstcolumninsheetevent@5.1)
-   [AlternateHeaderLineEvent](https://docs.typo3.org/permalink/calien/xlsexport:alternateheaderlineevent@5.1)
-   [ManipulateRowEntryEvent](https://docs.typo3.org/permalink/calien/xlsexport:manipulaterowentryevent@5.1)

The extension dispatches [PSR-14 events](https://docs.typo3.org/m/typo3/reference-coreapi/13.4/en-us/ApiOverview/Events/EventDispatcher/Index.html#EventDispatcher) that let you shape the
backend module, the export queries and the generated spreadsheet without replacing the controller.
Register a listener with the `\TYPO3\CMS\Core\Attribute\AsEventListener` attribute.

-   [Filtering exports](https://docs.typo3.org/permalink/calien/xlsexport:developer-filter@5.1) adds a filter form to the module and applies it to list and download.
-   The three events in the namespace `\Calien\Xlsexport\Event\Export` are dispatched by
    `\Calien\Xlsexport\Service\SpreadsheetWriteService` while the spreadsheet is written.

## Filtering exports {#developer-filter}

A filter consists of three parts, none of which requires overriding the controller:

1.  A form in the module, rendered by overriding the empty `Filter` partial.
1.  [ModifyExportModuleViewEvent](https://docs.typo3.org/permalink/calien/xlsexport:developer-module-view@5.1) to assign the options of the form.
1.  [ModifyExportCountQueryEvent](https://docs.typo3.org/permalink/calien/xlsexport:developer-count-query@5.1) and [ModifyExportQueryEvent](https://docs.typo3.org/permalink/calien/xlsexport:developer-export-query@5.1) to apply the submitted values to
    the record count in the overview and to the download.

The request parameter `filter` is reserved for this purpose. The module sanitizes its values to
strings and nested arrays of strings, hands them to the events and forwards them as hidden fields
with every download. Apply the same constraints in both query events, so the overview counts what
is downloaded.

### Rendering the filter form {#rendering-the-filter-form}

The module renders the partial `Filter` above the list of exports. It is empty by default.
Override it with the [backend template override](https://docs.typo3.org/m/typo3/reference-typoscript/13.4/en-us/PageTsconfig/Templates.html#pagetemplates) of page TSconfig, which
your extension can ship in [`Configuration/page.tsconfig`](https://docs.typo3.org/m/typo3/reference-coreapi/13.4/en-us/ExtensionArchitecture/FileStructure/Configuration/PageTsconfig.html#file-extension-configuration-page-tsconfig):

**EXT:my_extension/Configuration/page.tsconfig**

```typoscript
templates.calien/xlsexport.1731700000 = my-vendor/my-extension:Resources/Private/TemplateOverrides/Xlsexport
```

The partial then lives in
`EXT:my_extension/Resources/Private/TemplateOverrides/Xlsexport/Partials/Filter.html`. It
receives all module variables, among them:

-   **`filterUri`**

    Module URL of the current page. Submit the form to it with `method="post"`.

-   **`filter`**

    The currently applied filter values.

-   **`pageId`, `datasets`**

    The current page and the listed exports.

**EXT:my_extension/Resources/Private/TemplateOverrides/Xlsexport/Partials/Filter.html**

```html
<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers" data-namespace-typo3-fluid="true">
<form method="post" action="{filterUri}" class="row g-3 align-items-end mb-3">
    <div class="col-auto">
        <label for="filter-location" class="form-label">Location</label>
        <select id="filter-location" name="filter[location]" class="form-select">
            <option value="">All</option>
            <f:for each="{locations}" as="location">
                <option value="{location.uid}"
                    {f:if(condition: '{location.uid} == {filter.location}', then: 'selected')}>
                    {location.title}
                </option>
            </f:for>
        </select>
    </div>
    <div class="col-auto">
        <button type="submit" class="btn btn-default">Apply filter</button>
    </div>
</form>
</html>
```

## ModifyExportModuleViewEvent {#developer-module-view}

`\Calien\Xlsexport\Event\Module\ModifyExportModuleViewEvent` is dispatched before the
export overview of the module is rendered. Use it to assign the options of your filter form or to add
buttons to the document header.

-   *Mutable:* the module template, via `getModuleTemplate()`
-   *Read:* `getRequest()`, `getPageId()`, `getFilter()`, `getDatasets()`

**EXT:my_extension/Classes/EventListener/ProvideLocationFilter.php**

```php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\EventListener;

use Calien\Xlsexport\Event\Module\ModifyExportModuleViewEvent;
use MyVendor\MyExtension\Domain\Repository\LocationRepository;
use TYPO3\CMS\Core\Attribute\AsEventListener;

final class ProvideLocationFilter
{
    public function __construct(
        private readonly LocationRepository $locationRepository
    ) {}

    #[AsEventListener]
    public function __invoke(ModifyExportModuleViewEvent $event): void
    {
        $event->getModuleTemplate()->assign(
            'locations',
            $this->locationRepository->findByPage($event->getPageId())
        );
    }
}
```

## ModifyExportCountQueryEvent {#developer-count-query}

`\Calien\Xlsexport\Event\Query\ModifyExportCountQueryEvent` is dispatched once per export
before its record count is queried for the overview of the module. Use it to add the constraints and
joins of your filter.

-   *Mutable:* the query, via `getQueryBuilder()`
-   *Read:* `getConfigurationKey()` (the export key), `getPageId()`, `getFilter()`

Bind every value through `createNamedParameter()`. Do not add an `orderBy()`, as some
database platforms reject it on a count query. See [ModifyExportQueryEvent](https://docs.typo3.org/permalink/calien/xlsexport:developer-export-query@5.1) for an example.

## ModifyExportQueryEvent {#developer-export-query}

`\Calien\Xlsexport\Event\Query\ModifyExportQueryEvent` is dispatched before the query of
a download is executed. Use it to add the constraints and joins of your filter, or an ordering.

-   *Mutable:* the query, via `getQueryBuilder()`
-   *Read:* `getConfigurationKey()` (the export key), `getPageId()`, `getFilter()`

Bind every value through `createNamedParameter()`. A listener applying a filter usually handles
both query events, so the count in the overview matches the download:

**EXT:my_extension/Classes/EventListener/ApplyLocationFilter.php**

```php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\EventListener;

use Calien\Xlsexport\Event\Query\ModifyExportCountQueryEvent;
use Calien\Xlsexport\Event\Query\ModifyExportQueryEvent;
use TYPO3\CMS\Core\Attribute\AsEventListener;
use TYPO3\CMS\Core\Database\Connection;
use TYPO3\CMS\Core\Database\Query\QueryBuilder;

final class ApplyLocationFilter
{
    #[AsEventListener]
    public function filterCount(ModifyExportCountQueryEvent $event): void
    {
        if ($event->getConfigurationKey() === 'events') {
            $this->constrainLocation($event->getQueryBuilder(), $event->getFilter());
        }
    }

    #[AsEventListener]
    public function filterExport(ModifyExportQueryEvent $event): void
    {
        if ($event->getConfigurationKey() === 'events') {
            $this->constrainLocation($event->getQueryBuilder(), $event->getFilter());
        }
    }

    private function constrainLocation(QueryBuilder $queryBuilder, array $filter): void
    {
        $location = (int)($filter['location'] ?? 0);
        if ($location === 0) {
            return;
        }
        $queryBuilder->andWhere(
            $queryBuilder->expr()->eq(
                'location',
                $queryBuilder->createNamedParameter($location, Connection::PARAM_INT)
            )
        );
    }
}
```

## AlternateFirstColumnInSheetEvent {#developer-first-column}

Dispatched once, before anything is written, to decide the first spreadsheet column the header and
rows start in. The default is `A`. Use it to leave room for a logo or leading columns your own
listener fills.

-   *Mutable:* yes, via `setFirstColumn(string $firstColumn)`

**EXT:my_extension/Classes/EventListener/MoveExportStart.php**

```php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\EventListener;

use Calien\Xlsexport\Event\Export\AlternateFirstColumnInSheetEvent;
use TYPO3\CMS\Core\Attribute\AsEventListener;

final class MoveExportStart
{
    #[AsEventListener]
    public function __invoke(AlternateFirstColumnInSheetEvent $event): void
    {
        $event->setFirstColumn('B');
    }
}
```

## AlternateHeaderLineEvent {#developer-header-line}

Dispatched before the header row is written, carrying the field labels from `fieldLabels`
and the export key. Use it to translate, reorder or extend the column headers.

-   *Mutable:* yes, via `setHeaderFieldLabels(array $headerFieldLabels)`
-   *Read:* `getHeaderFieldLabels()`, `getConfiguration()` (the export key)

```php
#[AsEventListener]
public function __invoke(AlternateHeaderLineEvent $event): void
{
    if ($event->getConfiguration() === 'orders') {
        $event->setHeaderFieldLabels(['#', 'Order number', 'Total']);
    }
}
```

## ManipulateRowEntryEvent {#developer-row-entry}

Dispatched for every data row before it is written, carrying the raw row (as fetched from the
database), the header labels and the export key. Use it to format values, resolve foreign keys to
readable labels, or add computed columns.

-   *Mutable:* yes, via `setRow(array $row)`
-   *Read:* `getRow()`, `getFieldLabels()`, `getConfigurationKey()`

```php
#[AsEventListener]
public function __invoke(ManipulateRowEntryEvent $event): void
{
    $row = $event->getRow();
    $row['created'] = date('Y-m-d', (int)($row['created'] ?? 0));
    $event->setRow($row);
}
```
