ModifyLinkExplanationEvent

New in version 12.0

This event serves as a more powerful and flexible alternative for the removed $GLOBALS['TYPO3_CONF_VARS']['SYS']['formEngine']['linkHandler'] hook.

While the removed hook effectively only allowed to modify the link explanation of TCA link fields in case the resolved link type did not already match one of those, implemented by TYPO3 itself, the new event allows to always modify the link explanation of any type. Additionally, this also allows to modify the additionalAttributes, displayed below the actual link explanation field. This is especially useful for extended link handler setups.

To modify the link explanation, the following methods are available:

getLinkExplanation(): Returns the current link explanation data
setLinkExplanation(): Set the link explanation data
getLinkExplanationValue(): Returns a specific link explanation value
setLinkExplanationValue(): Sets a specific link explanation value

The link explanation array usually contains the following values:

text : The text to show in the link explanation field
icon: The markup for the icon, displayed in front of the link explanation field
additionalAttributes: The markup for additional attributes, displayed below the link explanation field

The current context can be evaluated using the following methods:

getLinkData(): Returns the resolved link data, such as the page uid
getLinkParts(): Returns the resolved link parts, such as url, target and additionalParams
getElementData(): Returns the full FormEngine $data array for the current element

Example

EXT:my_extension/Classes/Backend/EventListener/MyEventListener.php

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Backend\EventListener;

use TYPO3\CMS\Backend\Form\Event\ModifyLinkExplanationEvent;
use TYPO3\CMS\Core\Attribute\AsEventListener;
use TYPO3\CMS\Core\Imaging\IconFactory;
use TYPO3\CMS\Core\Imaging\IconSize;

#[AsEventListener(
    identifier: 'my-extension/backend/modify-link-explanation',
)]
final readonly class MyEventListener
{
    public function __construct(
        private IconFactory $iconFactory,
    ) {}

    public function __invoke(ModifyLinkExplanationEvent $event): void
    {
        // Use a custom icon for a custom link type
        if ($event->getLinkData()['type'] === 'myCustomLinkType') {
            $event->setLinkExplanationValue(
                'icon',
                $this->iconFactory->getIcon(
                    'my-custom-link-icon',
                    IconSize::SMALL,
                )->render(),
            );
        }
    }
}

New in version 13.0

The PHP attribute \TYPO3\CMS\Core\Attribute\AsEventListener has been introduced to tag a PHP class as an event listener. Alternatively, or if you need to be compatible with older TYPO3 versions, you can also register an event listener via the Configuration/Services.yaml file. Switch to an older version of this page for an example or have a look at the section Implementing an event listener in your extension.

API

class ModifyLinkExplanationEvent

Fully qualified name: \TYPO3\CMS\Backend\Form\Event\ModifyLinkExplanationEvent

Listeners to this Event will be able to modify the link explanation array, used in FormEngine for link fields

getLinkData ( )

Returns: array

getLinkParts ( )

Returns: array

getElementData ( )

Returns: array

getLinkExplanation ( )

Returns: array

setLinkExplanation ( array $linkExplanation)

param $linkExplanation: the linkExplanation

getLinkExplanationValue ( string $key, ?mixed $default = NULL)

param $key: the key
param $default: the default, default: NULL

Returns: ?mixed

setLinkExplanationValue ( string $key, ?mixed $value)

param $key: the key
param $value: the value