[FEATURE] UI: interface for confirmation prompts

[thibsy]

Hi @fhelfer,

As a result of looking into ILIAS-eLearning#10031 and trying to propose some directions, I already tried to take care of most interface changes.

Before talking about the proposed interface here, let me show you how a "confirmation prompt" could already be implemented right now by making two small changes: 1) make Prompt\State\Factory::show() accept more than one Prompt\IsPromptContent and 2) make the Listing\Entity\Standard such a content. Then your endpoint would look like:

$entities = [1, 2, 3]; // just some ids for demo

$retrieval = new class ($entities) implements DataRetrieval {
    public function __construct(protected array $entities)
    {
    }
    public function getEntities(Mapping $mapping, ?Range $range, ?array $additional_parameters): \Generator
    {
        foreach ($this->entities as $entity) {
            yield $mapping->map($entity);
        }
    }
};
$mapping = new class () implements RecordToEntity {
    public function map(UIFactory $ui_factory, mixed $record): Entity
    {
        return $ui_factory->entity()->standard("primary ($record)", 'secondary');
    }
};
$state = $factory->prompt()->state()->show(
    $factory->messageBox()->confirmation('you sure about this?'),
    $factory->listing()->entity()->standard($mapping)->withData($retrieval),
    $factory->input()->container()->form()->standard('#', [
        'entity_ids' => array_reduce($entities, fn($inputs, $entity) => $factory->input()->field()->hidden()->withValue($entity)),
    ]),
);

This endpoint has two major drawbacks though:

• There is a crucial entanglement between the form and entity listing going on, which will not be visible in production code. Its also questionable how the entities can be shared by these components easily, since everything should be in a dedicated class there. Its very fragile.
• The entanglement is the consumers responsibility, who needs to take care of everything and has to be informed. This will lead to many different solutions for the same problem, while it also adds much unnecessary overhead.

So the main goals for my interface were:

• Let the UI framework take care of any entanglement.
• Make implementations as easy as possible.

The first goal I achieved by passing a combination of EntityRetrieval and array<string|int> of entity IDs for creating a new confirmation prompt state. This would actually allows us to omit technical identifiers on the Entity itself, but I think it could be beneficial in the future. It also makes passing along the entity ids internally easier for this state.

I know this combination is kind of stupid, because the consumer is in control of both (retrieval and entity ids) and could simply provide an array<Entity> directly. But there's a thought process behind it: if we shift the request handling closer to the UI framework, it may be possible for the UI framework to take care of fetching the ids from the request. Then we only need an interface for consumers to create entities. In addition, this forces consumers to create an entity retrieval for their component and this will probably lead to more structure.

The second goal is a bit hard to measure, but I believe to address it by encapsulating most of the concrete confirmation state behind arguments. I only require the necessary information to build the entity listing, form and message box completely internal. This way we avoid different solutions to the problem and can easily roll out adjustments.

I also simplified the interface of the entity listing, because these two different mappings IMO were complete nonsense. The retrieval now just creates entities directly. This will also simplify the internals, I assume. Since you probably want to use the existing listing and alter it by using context rendering, this should come in handy.

Let me know if you can work with this, or if we should discuss this on Discord.

Best,
@thibsy

[thibsy]

@fhelfer you need to sync trunk to view this PR properly.