Feature: #89244 - Broadcast Channels and Messaging

See forge#89244

Description

It is now possible to send broadcast messages from anywhere in TYPO3 that are listened to via JavaScript.

Warning

This API is considered internal and may change anytime until declared being stable.

Send a message

Any backend module may send a message using the TYPO3/CMS/Backend/BroadcastService module. The payload of such message is an object that consists at least of the following properties:

  • componentName - the name of the component that sends the message (e.g. extension name)

  • eventName - the event name used to identify the message

A message may contain any other property as necessary. The final event name to listen is a composition of "typo3", the component name and the event name, e.g. typo3:my_extension:my_event.

Attention

Since a polyfill is in place to add support for Microsoft Edge, the payload must contain JSON-serializable content only.

To send a message, the post() method has to be used.

Example code:

require(['TYPO3/CMS/Backend/BroadcastService'], function (BroadcastService) {
  const payload = {
    componentName: 'my_extension',
    eventName: 'my_event',
    hello: 'world',
    foo: ['bar', 'baz']
  };

  BroadcastService.post(payload);
});

Receive a message

To receive and thus react on a message, an event handler needs to be registered that listens to the composed event name (e.g. typo3:my_component:my_event) sent to document.

The event itself contains a property called detail excluding the component name and event name.

Example code:

define([], function() {
   document.addEventListener('typo3:my_component:my_event', (e) => eventHandler(e.detail));

   function eventHandler(detail) {
     console.log(detail); // contains 'hello' and 'foo' as sent in the payload
   }
});

Hook into $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['typo3/backend.php']['constructPostProcess'] to load a custom BackendController hook that loads the event handler, e.g. via RequireJS.

Example code:

// ext_localconf.php
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['typo3/backend.php']['constructPostProcess'][]
    = \Vendor\MyExtension\Hooks\BackendControllerHook::class . '->registerClientSideEventHandler';

// Classes/Hooks/BackendControllerHook.php
class BackendControllerHook
{
    public function registerClientSideEventHandler(): void
    {
        $pageRenderer = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\TYPO3\CMS\Core\Page\PageRenderer::class);
        $pageRenderer->loadRequireJsModule('TYPO3/CMS/MyExtension/EventHandler');
    }
 }