Feature: #97544 - PSR-14 events for modifying preview URIs

Description

Two new PSR-14 events \TYPO3\CMS\Backend\Routing\Event\BeforePagePreviewUriGeneratedEvent and \TYPO3\CMS\Backend\Routing\Event\AfterPagePreviewUriGeneratedEvent have been introduced. Those serve as a direct replacement for the now deprecated $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_befunc.php']['viewOnClickClass'] hook.

The BeforePagePreviewUriGeneratedEvent is executed in the PreviewUriBuilder->buildUri(), before the preview URI is actually built. It allows to either adjust the parameters, such as the page ID or the language ID, or to set a custom preview URI, which will then stop the event propagation and also prevents PreviewUriBuilder from building the URI based on the parameters.

Methods of BeforePagePreviewUriGeneratedEvent:

• setPreviewUri(UriInterface $uri)
• getPageId()
• setPageId(int $pageId)
• getLanguageId()
• setLanguageId(int $languageId)
• getRootline()
• setRootline(array $rootline)
• getSection()
• setSection(string $section)
• getAdditionalQueryParameters()
• setAdditionalQueryParameters(array $additionalQueryParameters)
• getContext()
• getOptions()

The AfterPagePreviewUriGeneratedEvent is executed in the PreviewUriBuilder->buildUri(), after the preview URI has been built - or set by an event listener to BeforePagePreviewUriGeneratedEvent. It allows to overwrite the built preview URI. This event however does not feature the possibility to modify the parameters, since this won't have any effect as the preview URI is directly returned after event dispatching and no further action is done by the PreviewUriBuilder.

Methods of AfterPagePreviewUriGeneratedEvent:

• setPreviewUri(UriInterface $uri)
• getPreviewUri()
• getPageId()
• getLanguageId()
• getRootline()
• getSection()
• getAdditionalQueryParameters()
• getContext()
• getOptions()

Example

Registration of the event in your extension's Services.yaml:

MyVendor\MyPackage\Backend\MyEventListener:
  tags:
    - name: event.listener
      identifier: 'my-package/backend/modify-parameters'
      method: 'modifyParameters'
    - name: event.listener
      identifier: 'my-package/backend/modify-preview-uri'
      method: 'modifyPreviewUri'

The corresponding event listener class:

use TYPO3\CMS\Backend\Routing\Event\AfterPagePreviewUriGeneratedEvent;
use TYPO3\CMS\Backend\Routing\Event\BeforePagePreviewUriGeneratedEvent;

final class MyEventListener
{
    public function modifyParameters(BeforePagePreviewUriGeneratedEvent $event): void
    {
        // Add custom query parameter before URI generation
        $event->setAdditionalQueryParameters(
            array_replace_recursive(
                $event->getAdditionalQueryParameters(),
                ['myParam' => 'paramValue']
            )
        );
    }

    public function modifyPreviewUri(AfterPagePreviewUriGeneratedEvent $event): void
    {
        // Add custom fragment to built preview URI
        $uri = $event->getPreviewUri();
        $uri = $uri->withFragment('#customFragment');
        $event->setPreviewUri($uri);
    }
}

Impact

It's now possible to modify the parameters used to build a preview URI and also to directly set a custom preview URI, using the new PSR-14 event BeforePagePreviewUriGeneratedEvent. It's also now possible to modify or completely replace a built preview URI using the new PSR-14 event AfterPagePreviewUriGeneratedEvent.