[FEATURE] Feature: #97187 - PSR-14 Event for modifying link explanati…

…on (#1794)

* [FEATURE] Feature: #97187 - PSR-14 Event for modifying link explanation

https://docs.typo3.org/c/typo3/cms-core/main/en-us/Changelog/12.0/Feature-97187-PSR-14EventForModifyingLinkExplanation.html

refs #1624

* Update ModifyLinkExplanationEvent.rst

Co-authored-by: lina.wolf <[email protected]>

Documentation/ApiOverview/Hooks/Events/Backend/ModifyLinkExplanationEvent.rst

@@ -0,0 +1,80 @@
+.. include:: /Includes.rst.txt
+.. index:: Events; ModifyLinkExplanationEvent
+.. _ModifyLinkExplanationEvent:
+
+=============================
+ModifyLinkExplanationEvent
+=============================
+
+.. versionadded:: 12.0
+   This event serves as a more powerful and flexible alternative
+   for the removed :php:`$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, does the new Event now allow 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:
+
+- :php:`getLinkExplanation()`: Returns the current link explanation data
+- :php:`setLinkExplanation()`: Set the link explanation data
+- :php:`getLinkExplanationValue()`: Returns a specific link explanation value
+- :php:`setLinkExplanationValue()`: Sets a specific link explanation value
+
+The link explanation array usually contains the following values:
+
+- :php:`text` : The text to show in the link explanation field
+- :php:`icon`: The markup for the icon, displayed in front of the link explanation field
+- :php:`additionalAttributes`: The markup for additional attributes, displayed below the link explanation field
+
+The current context can be evaluated using the following methods:
+
+- :php:`getLinkData()`: Returns the resolved link data, such as the page uid
+- :php:`getLinkParts()`: Returns the resolved link parts, such as `url`, `target` and `additionalParams`
+- :php:`getElementData()`: Returns the full FormEngine `$data` array for the current element
+
+API
+===
+
+.. include:: /CodeSnippets/Events/Backend/ModifyLinkExplanationEvent.rst.txt
+
+Example
+=======
+
+Registration of the Event in your extensions' :file:`Services.yaml`:
+
+.. code-block:: yaml
+   :caption: EXT:my_extension/Configuration/Services.yaml
+
+   MyVendor\MyExtension\Backend\ModifyLinkExplanationEventListener:
+     tags:
+       - name: event.listener
+         identifier: 'my-package/backend/modify-link-explanation'
+
+The corresponding event listener class:
+
+.. code-block:: php
+   :caption: EXT:my_extension/Classes/Backend/ModifyLinkExplanationEventListener.php
+
+   use TYPO3\CMS\Backend\Form\Event\ModifyLinkExplanationEvent;
+   use TYPO3\CMS\Core\Imaging\Icon;
+   use TYPO3\CMS\Core\Imaging\IconFactory;
+
+   final class ModifyLinkExplanationEventListener
+   {
+       public function __construct(protected readonly 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', Icon::SIZE_SMALL)->render());
+           }
+       }
+   }

Documentation/CodeSnippets/Events/Backend/ModifyLinkExplanationEvent.rst.txt

@@ -0,0 +1,39 @@
+.. Generated by https://github.com/linawolf/t3docs_restructured_api_tools 
+.. php:namespace::  TYPO3\CMS\Backend\Form\Event
+
+.. php:class:: ModifyLinkExplanationEvent
+
+   Listeners to this Event will be able to modify the link explanation array, used in FormEngine for link fields
+
+
+   .. php:method:: getLinkData()
+   
+      :returntype: array
+
+   .. php:method:: getLinkParts()
+   
+      :returntype: array
+
+   .. php:method:: getElementData()
+   
+      :returntype: array
+
+   .. php:method:: getLinkExplanation()
+   
+      :returntype: array
+
+   .. php:method:: setLinkExplanation(array linkExplanation)
+   
+      :param array $linkExplanation: the linkExplanation
+
+   .. php:method:: getLinkExplanationValue(string key, mixed default = NULL)
+   
+      :param string $key: the key
+      :param mixed $default: the default, default: NULL
+      :returntype: mixed
+
+   .. php:method:: setLinkExplanationValue(string key, mixed value)
+   
+      :param string $key: the key
+      :param mixed $value: the value
+