ModifyProfileDemandEvent 

When it is dispatched 

ProfileRepository dispatches the event before it builds a query from a demand:

• List and list-and-detail plugins, list action: once for the profiles of the list, on a copy of the demand of the request after the settings of the content element and the filters of the visitor were adopted. ModifyProfileQueryEvent follows.
• Once more, on a copy of that demand, while the content element shows only contracts valid today, for the next day on which the list changes. That day caps the page cache lifetime. A demand with profiles selected by hand is not asked.
• Once more, on a copy of that demand without the letter, while the content element shows the letter navigation and no profiles are selected by hand, for the letters that lead to a list that is not empty, see Which letters lead somewhere.
• Card plugin: once for the profiles of the card, on a copy of a demand of its own that carries the selection of the card, the language fallback and the hidden records setting, and nothing else.

Every call receives a copy of the demand the plugin built, never one a listener changed on an earlier call of the same rendering.

The detail, selected-profiles and selected-contracts plugins do not dispatch it. Neither does the filter form of the list, which only redirects to the list it asks for.

What a listener reads and changes 

What the query reads from the demand: the storage folders, the profiles selected by hand, the grouping, the sort field and its direction, the letter, the function types and organisational units of the content element, the two filters of the visitor, the language fallback, the hidden records setting and whether only contracts valid today count. A sort field or a grouping that is not one of the allowed values of the extension configuration is ignored.

The event carries no plugin context. A listener that has to tell the plugins apart reads the demand, a selection by hand for example, or uses ModifyProfileQueryEvent, which carries the context.

Example 

A site wants every list for which an editor chose No sorting to come out by last name rather than in the order the profiles were created:

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\EventListener;

use FGTCLB\AcademicPersons\Event\ModifyProfileDemandEvent;
use TYPO3\CMS\Core\Attribute\AsEventListener;

final class SortUnsortedListsByLastName
{
    #[AsEventListener(identifier: 'my-extension/sort-unsorted-lists-by-last-name')]
    public function __invoke(ModifyProfileDemandEvent $event): void
    {
        $demand = $event->getDemand();
        // A selection by hand keeps the order of the selection anyway.
        if ($demand->getSortBy() !== '' || $demand->getProfileList() !== '') {
            return;
        }
        // The demand is a copy, so it is changed in place.
        $demand->setSortBy('lastName');
        $demand->setSortByDirection('asc');
    }
}

Rules and pitfalls 

• A changed demand reaches the repository only, whether the listener changed it in place or replaced it. It decides which profiles are queried, which letters are offered and how long the page is cached. The active letter, the pagination, the page, the order of a selection by hand, the view mode, the links of the navigation and the demand the template receives keep following the demand of the request, see What the navigation links carry.
• A selection by hand the listener sets decides the query only. The list renders its profiles in the order of their uids, and offers the letter navigation while the content element enables it, every letter leading to the same profiles. A list is ordered by hand only by a selection of the content element.
• Answer all calls for one list alike. A listener that narrows the list but not the letters makes the navigation offer letters that lead to an empty list.
• The visitor filters arrive checked: a function type or organisational unit the content element does not offer is 0 by then. A value the listener sets itself is applied as it is.

Introduced in 

The event is part of the extension since its first release. Later changes:

• Important: Sort direction is normalised (2.4) normalises the sort direction a listener sets.
• Important: Demand listeners work on a copy (2.4) hands the listeners of the list query a copy, so a change in place reaches the query only. The two further calls of 3.0 work on copies from the start.
• Breaking: The list, detail and selection events of the plugins are gone made it the place to change which profiles a list queries, instead of the removed list event.
• Feature: The letter navigation knows which letters lead somewhere dispatches it for the letters as well.
• Feature: Visitors filter the list by function type and by unit added the two visitor filters to the demand.
• Important: The profile queries see a letter switching off the pagination describes when a letter switches the pagination off.