Improvement: refine UI input method contracts & component documentation

[GitHamo]

This PR enhances method signatures in the UI component Input interfaces.

The changes include:

• getStepSize(): Added contract definition to Numeric interface.
• getDedicatedName(): Added contract definition to Input interface.
• Corrected dockblock in UI\Component\Component.

Note: declared methods already exist in related implementations.

Why are these methods needed in the public contracts?

ILIAS\Component\Activities\Activity::getInputDescription() exposes the UI input description that serves as a machine-readable schema for activity input validation. [L]

As part of the new ILIAS Webservices component, we plan to consume the input description from the activities in REST endpoints. We currently want to use this schema in two places:

getDedicatedName()

getDedicatedName() is used to reconstruct the input mapping and validate incoming webservice requests against the expected form input names.

Example:

/**
 * @var \ILIAS\UI\Factory $factory
 * @var \ILIAS\Component\Activities\Activity $activity
 * @var \ILIAS\UI\Component\Input\Container\Form\FormInput $inputDescription
 * @var array<\ILIAS\UI\Component\Input\Container\Form\FormInput> $inputs
 */
$inputDescription = $activity->getInputDescription();
$inputs = $inputDescription->getInputs();

// Reconstruct associative array using dedicated names to ensure form mapping works correctly.
$namedInputs = [];

foreach ($inputs as $input) {
    $dedicatedName = $input->getDedicatedName();
    $key = ($dedicatedName !== null && $dedicatedName !== '')
        ? $dedicatedName
        : $input->getLabel();

    $namedInputs[$key] = $input;
}

$form = $factory->input()
    ->container()
    ->form()
    ->standard('', $namedInputs);

getStepSize()

getStepSize() is used to determine the appropriate OpenAPI numeric type (integer or number) when generating the API specification.

See: https://swagger.io/docs/specification/v3_0/data-models/data-types/#numbers

Example:

/** @var \ILIAS\UI\Component\Input\Input $input */
$stepSize = (float) $input->getStepSize();
$hasPrecision = (floor($stepSize) !== $stepSize);

$type = $hasPrecision ? 'number' : 'integer';
$format = $hasPrecision ? 'double' : '';

Existing public implementations

The proposed methods are already declared public in their corresponding implementation classes:

• ILIAS\UI\Implementation\Component\Input\Input::getDedicatedName() (also has @inheritdoc)
• ILIAS\UI\Implementation\Component\Input\Field\Numeric::getStepSize()

This change adds them to the corresponding interfaces so consumers of getInputDescription() can rely on the public contracts instead of concrete implementation classes.

[thibsy]

Hi @GitHamo,

Thx a lot for your contribution to the UI framework!

Please help me answer the following questions:

• Public getters: you expose the getStepSize() and getDedicatedName() getters on the public interface. Could you explain why you need those methods when working with the inputs? What is your use-case? We normally try and keep most of our getters strictly internal, so if there is not an important reason, we would like to keep it this way.

Kind regards,
@thibsy (as UI coordinator)

[GitHamo]

Hi @thibsy, thank you very much for your comment. I have updated the PR description with the concrete use cases that require these methods.

We are working on a new webservices component that consumes the UI input description exposed through ILIAS\Component\Activities\Activity::getInputDescription() [L]

The declared methods are already public in related implementations, and I could just use the implementation signature directly, but I prefer to use the interface instead since we want to keep the domain & infrastructure layers overlap to a minimum.

One of the methods even has an @inheritdoc PHPDoc, which suggests it may have originally been intended to be part of the public contract.

• ILIAS\UI\Implementation\Component\Input\Input: declared public, has phpdoc @inheritdoc
• ILIAS\UI\Implementation\Component\Input\Field\Numeric: declared public

Please let me know if I should clarify anything.

Cheers,
Ahmed

[thibsy]

Hi @GitHamo,

thx for your detailed feedback.

I will need some time to digest this together with @chfsx, because we are unsure if the UI inputs should be used directly in this instance. We can see how a looser coupling between UI and Component (Activities), achieved by something equivalent of the GS, could be beneficial.

Regarding your comment

[...] I could just use the implementation signature directly, but I prefer to use the interface instead [...].

I think this is the wrong mindset =). We take our interface segregation very seriously inside the UI framework, there is even a whole paper about it. Just because you can access it, doesn't mean you ever should. This is clearly a mismatch of our APIs. I know that you brought this to our attention now, but just for future reference, you should not reach into internals of other components without contacting respective authorities, especially if you are in an advanced stage of your implementation.

Kind regards,
@thibsy