Backend Filter

composer require digitalzombies/be_filter

TCEFORM.tx_my_table.status.removeItems = draft
TCEFORM.tx_my_table.status.altLabels.done = Finished

// The number filters of the car table. Bounds and step come from the column,
// both may be overridden here.

// A slider with two handles for the range. It needs both ends: the column only
// says where the prices start, so the filter says where they end.
'price' => ['default' => true, 'step' => 500, 'max' => 200000, 'render' => 'slider'],
// A slider with one handle, bounding the range at the top.
'mileage' => ['max' => 300000, 'step' => 1000, 'render' => 'slider', 'mode' => 'max'],
// A decimal column: the step follows the precision.
'consumption' => ['decimals' => 1, 'step' => 0.1],

// A date filter whose two ends carry captions of their own.
'first_registration' => [
    'default' => true,
    'labels' => ['from' => $language . 'car.registeredFrom', 'to' => $language . 'car.registeredTo'],
],

'crdate' => [
    'type' => 'date',
    'presets' => [
        'thisMonth' => true,                                          // a default, unchanged
        'week'      => ['label' => 'LLL:EXT:my_ext/…:last7days'],      // a default, own label
        'quarter'   => ['label' => 'Quarter', 'from' => '-3 months'],  // a new one
        'overdue'   => ['label' => 'Overdue', 'to' => 'yesterday'],    // open at the start
    ],
],

// ext_localconf.php
$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['be_filter']['datePresets']['week'] = [
    'label' => 'LLL:EXT:my_ext/…:last7days',
    'from' => '-7 days',
];

#[AsEventListener('my/scope-filter-options')]
public function __invoke(ModifyFilterQueryEvent $event): void
{
    $this->addMyConstraint($event->getQueryBuilder(), $event->getTable());
}

#[AsEventListener('my/scope-presets')]
public function scopePresets(ModifyPresetQueryEvent $event): void
{
    $event->setScope('tenant', $this->tenantContext->getCurrentTenant());
}

// packages/example-fleet/Configuration/TCA/tx_examplefleet_domain_model_car.php
// $language is the LLL prefix of the extension.
    'filters' => [
        // A relation, offered with a limit of its own: the bar says how many it hides.
        'manufacturer' => ['default' => true, 'optionLimit' => 5],
        // Narrowed by its parent, several values at once.
        'model' => ['default' => true, 'multiple' => true, 'dependsOn' => 'manufacturer'],
        'fuel' => ['default' => true, 'multiple' => true],
        'body' => ['multiple' => true],
        // An MM relation, narrowed by a parent as well.
        'features' => ['multiple' => true, 'dependsOn' => 'manufacturer'],
        // Two parents narrow this one.
        'dealer' => ['multiple' => true, 'dependsOn' => ['manufacturer', 'model']],
        // A checkbox as the yes / no dropdown, which is the default.
        'available' => ['default' => true],
        // A filter type of this extension, see Classes/Filter/Type. It takes the column
        // from the built in select type by answering a higher priority.
        'colour' => [
            'render' => 'swatches',
            'swatches' => [
                'black' => '#1d1d1b',
                'white' => '#f2f2f2',
                'silver' => '#c8ccce',
                'blue' => '#1b4ea0',
                'red' => '#c8102e',
                'green' => '#2e7d32',
            ],
        ],
        // Captions of its own for the two ends of the range.
        'first_registration' => [
            'default' => true,
            'labels' => ['from' => $language . 'car.registeredFrom', 'to' => $language . 'car.registeredTo'],
        ],
        // Bounds and step come from the column, both may be overridden here.
        // A slider with two handles for the range. It needs both ends: the column only
        // says where the prices start, so the filter says where they end.
        'price' => ['default' => true, 'step' => 500, 'max' => 200000, 'render' => 'slider'],
        // A slider with one handle, bounding the range at the top.
        'mileage' => ['max' => 300000, 'step' => 1000, 'render' => 'slider', 'mode' => 'max'],
        // A decimal column: the step follows the precision.
        'consumption' => ['decimals' => 1, 'step' => 0.1],
        // A field without a TCA column needs its type, and a label of its own.
        'crdate' => ['type' => 'date', 'label' => $language . 'car.created'],
        // The same checkbox as a switch instead of the dropdown.
        'hidden' => ['render' => 'checkbox'],
    ],

<?php
// Every setting has three levels: the installation, one table, one filter.
// The narrower level wins, and for captions it wins per end of the range.

// ext_localconf.php — the default for every table
$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['be_filter']['autoRefresh'] = true;
$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['be_filter']['optionLimit'] = 50;
$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['be_filter']['labels'] = [
    'from' => 'LLL:EXT:my_ext/Resources/Private/Language/locallang.xlf:since',
    'to' => 'LLL:EXT:my_ext/Resources/Private/Language/locallang.xlf:until',
];

// One table decides for itself.
$GLOBALS['TCA']['tx_my_table']['ctrl']['be_filter'] = [
    'autoRefresh' => false,
    'optionLimit' => 200,
    'labels' => ['from' => 'Registered from'],
];

// One filter decides for itself.
$GLOBALS['TCA']['tx_my_table']['filters']['first_registration'] = [
    'labels' => ['from' => 'Registered from', 'to' => 'Registered until'],
];

mod.be_filter.disabled = 1                         # nobody in this group filters
mod.be_filter.tables.tx_my_table.disabled = 1      # or only this table is off limits

use DigitalZombies\BeFilter\Filter\Filter;
use DigitalZombies\BeFilter\Filter\Type\AbstractFilterType;
use Doctrine\DBAL\Query\Expression\CompositeExpression;
use TYPO3\CMS\Core\Database\Query\QueryBuilder;

final class MyFilterType extends AbstractFilterType
{
    public function getIdentifier(): string
    {
        // The name of the type, and of its control on the client
    }

    public function matches(array $config, array $definition): bool
    {
        // Whether this type takes over the filter
    }

    public function normalizeValue(mixed $value, Filter $filter): mixed
    {
        // What the filter accepts, NULL when the value constrains nothing
    }

    public function buildConstraint(
        QueryBuilder $queryBuilder,
        Filter $filter,
        mixed $value
    ): string|CompositeExpression|null {
        // The constraint added to the listing
    }
}

// packages/example-fleet/Classes/Filter/Type/ColourSwatchFilterType.php
<?php

declare(strict_types=1);

namespace DigitalZombies\ExampleFleet\Filter\Type;

use DigitalZombies\BeFilter\Filter\Filter;
use DigitalZombies\BeFilter\Filter\Type\AbstractFilterType;
use Doctrine\DBAL\Query\Expression\CompositeExpression;
use TYPO3\CMS\Core\Database\Connection;
use TYPO3\CMS\Core\Database\Query\QueryBuilder;
use TYPO3\CMS\Core\Localization\LanguageService;

/**
 * A filter type of an application: the colour of a car as swatches instead of a dropdown.
 * Nothing registers it by hand, the container collects it, see the README of be_filter.
 */
final class ColourSwatchFilterType extends AbstractFilterType
{
    public function getIdentifier(): string
    {
        return 'colourSwatches';
    }

    /**
     * The column belongs to the built in select type, so this one has to be asked first.
     */
    public function getPriority(): int
    {
        return 10;
    }

    public function matches(array $config, array $definition): bool
    {
        return (string)($config['type'] ?? '') === 'select'
            && (string)($definition['render'] ?? '') === 'swatches';
    }

    /**
     * @param array<string, mixed> $definition
     * @param array<string, mixed> $config
     * @return array<string, mixed>
     */
    public function buildTypeOptions(array $definition, array $config): array
    {
        $colours = is_array($definition['swatches'] ?? null) ? $definition['swatches'] : [];

        $swatches = [];
        foreach ((array)($config['items'] ?? []) as $item) {
            $value = (string)($item['value'] ?? '');
            if ($value === '' || !isset($colours[$value])) {
                continue;
            }
            $swatches[] = [
                'value' => $value,
                'label' => $this->getLanguageService()->sL((string)($item['label'] ?? '')) ?: $value,
                'colour' => (string)$colours[$value],
            ];
        }

        return ['swatches' => $swatches];
    }

    /**
     * @return array<string, mixed>
     */
    public function describe(Filter $filter): array
    {
        return ['swatches' => $filter->typeOptions['swatches'] ?? []];
    }

    /**
     * @return string[]|null
     */
    public function normalizeValue(mixed $value, Filter $filter): ?array
    {
        $known = array_column((array)($filter->typeOptions['swatches'] ?? []), 'value');
        $chosen = array_values(array_intersect(
            array_map(static fn(mixed $entry): string => is_scalar($entry) ? (string)$entry : '', (array)$value),
            $known
        ));

        return $chosen === [] ? null : $chosen;
    }

    public function buildConstraint(
        QueryBuilder $queryBuilder,
        Filter $filter,
        mixed $value
    ): string|CompositeExpression|null {
        $chosen = (array)$value;
        if ($chosen === []) {
            return null;
        }

        return $queryBuilder->expr()->in(
            $filter->table . '.' . $filter->name,
            $queryBuilder->createNamedParameter($chosen, Connection::PARAM_STR_ARRAY)
        );
    }

    public function getJavaScriptModule(): ?string
    {
        return '@digitalzombies/example-fleet/colour-filter.js';
    }

    private function getLanguageService(): LanguageService
    {
        return $GLOBALS['LANG'];
    }
}

# packages/example-fleet/Configuration/Services.yaml
services:
  _defaults:
    autowire: true
    autoconfigure: true
    public: false

  # Filter types are collected by tag, and a tag from another extension does not reach
  # this file: an extension adding a type tags it itself.
  _instanceof:
    DigitalZombies\BeFilter\Filter\Type\FilterTypeInterface:
      tags: ['be_filter.filter_type']

  DigitalZombies\ExampleFleet\:
    resource: '../Classes/*'

// packages/example-fleet/Resources/Public/JavaScript/colour-filter.js
import { html } from "lit";
import { AbstractFilterControl, registerFilterType } from "@digitalzombies/be_filter/filter-types.js";

const DOT = "display:inline-block;inline-size:.8rem;block-size:.8rem;border-radius:50%;"
  + "margin-inline-end:.4rem;border:1px solid rgba(0, 0, 0, .25);flex:0 0 auto";

/**
 * The colour of a car as swatches, the control of the "colourSwatches" type.
 */
class ColourSwatchFilter extends AbstractFilterControl {
  get swatches() {
    return this.filter.swatches ?? [];
  }

  // The bar hands NULL to a filter that is not set.
  get selection() {
    return this.value ?? [];
  }

  renderControl() {
    return html`
      <div class="be-filter-grid">
        ${this.swatches.map((swatch) => this.renderSwatch(swatch))}
      </div>`;
  }

  renderSwatch(swatch) {
    const chosen = this.selection.includes(swatch.value);

    return html`
      <button
        type="button"
        class="btn btn-sm ${chosen ? "btn-primary" : "btn-default"}"
        style="display:flex;align-items:center;text-align:start"
        aria-pressed=${chosen ? "true" : "false"}
        @click=${() => this.toggle(swatch.value)}
      >
        <span style="${DOT};background-color:${swatch.colour}"></span>
        <span>${swatch.label}</span>
      </button>`;
  }

  toggle(value) {
    const chosen = this.selection.includes(value)
      ? this.selection.filter((entry) => entry !== value)
      : [...this.selection, value];

    this.emit(chosen.length > 0 ? chosen : null);
  }

  summary() {
    const chosen = this.selection;

    return this.swatches
      .filter((swatch) => chosen.includes(swatch.value))
      .map((swatch) => swatch.label)
      .join(", ");
  }
}

customElements.define("example-fleet-colour-filter", ColourSwatchFilter);
registerFilterType("colourSwatches", "example-fleet-colour-filter");

export { ColourSwatchFilter };

// packages/example-fleet/Configuration/JavaScriptModules.php
<?php

return [
    'dependencies' => [
        'backend',
        'core',
        'be_filter',
    ],
    'imports' => [
        '@digitalzombies/example-fleet/' => 'EXT:example_fleet/Resources/Public/JavaScript/',
    ],
];

// The car column handed to the filter type of the application. It takes the column
// from the built in select type by answering a higher priority.
'colour' => [
    'render' => 'swatches',
    'swatches' => [
        'black' => '#1d1d1b',
        'white' => '#f2f2f2',
        'silver' => '#c8ccce',
        'blue' => '#1b4ea0',
        'red' => '#c8102e',
        'green' => '#2e7d32',
    ],
],

// packages/be_filter/Classes/Filter/Type/CheckboxFilterType.php — a built in type
// is written exactly like one an extension adds.
<?php

declare(strict_types=1);

namespace DigitalZombies\BeFilter\Filter\Type;

use DigitalZombies\BeFilter\Filter\Filter;
use TYPO3\CMS\Core\Database\Connection;
use TYPO3\CMS\Core\Database\Query\QueryBuilder;

/**
 * A single checkbox, offered as a yes / no dropdown or as a switch.
 */
final class CheckboxFilterType extends AbstractFilterType
{
    public function getIdentifier(): string
    {
        return 'checkbox';
    }

    public function matches(array $config, array $definition): bool
    {
        // Several items are a bitmask, which is not a single yes or no.
        return (string)($config['type'] ?? '') === 'check' && count((array)($config['items'] ?? [[]])) <= 1;
    }

    public function buildTypeOptions(array $definition, array $config): array
    {
        return ['checkbox' => (string)($definition['render'] ?? '') === 'checkbox'];
    }

    public function normalizeValue(mixed $value, Filter $filter): ?string
    {
        $value = is_scalar($value) ? (string)$value : '';

        if ($filter->asCheckbox()) {
            return $value === '1' ? '1' : null;
        }

        return in_array($value, ['0', '1'], true) ? $value : null;
    }

    public function buildConstraint(QueryBuilder $queryBuilder, Filter $filter, mixed $value): ?string
    {
        $value = (string)$value;
        if (!in_array($value, ['0', '1'], true)) {
            return null;
        }

        $checked = $value === '1';
        if ($filter->isInverted()) {
            $checked = !$checked;
        }

        return $queryBuilder->expr()->eq(
            $filter->table . '.' . $filter->name,
            $queryBuilder->createNamedParameter($checked ? 1 : 0, Connection::PARAM_INT)
        );
    }

    public function getJavaScriptModule(): ?string
    {
        return '@digitalzombies/be_filter/checkbox-filter.js';
    }
}

final class MySelectFilterType extends AbstractFilterType
{
    public function getIdentifier(): string
    {
        return 'select';          // the name of the built in type
    }

    public function getPriority(): int
    {
        return 10;                // built in types answer 0
    }

    public function getJavaScriptModule(): ?string
    {
        return '@my-vendor/my-ext/select-filter.js';
    }

    // … matches(), normalizeValue() and buildConstraint() as for any other type
}

composer require digitalzombies/be_filter
vendor/bin/typo3 extension:setup

# PHP, no TYPO3 instance needed
ddev exec vendor/bin/phpunit -c packages/be_filter/phpunit.xml.dist

# JavaScript, the specifiers are stubbed by a loader
ddev exec bash -c 'node --import ./packages/be_filter/Tests/JavaScript/register.mjs \
  --test packages/be_filter/Tests/JavaScript/*.test.mjs'

ddev exec vendor/bin/php-cs-fixer fix --dry-run --diff   # what would change
ddev exec vendor/bin/php-cs-fixer fix                    # change it