Attention

TYPO3 v10 has reached end-of-life as of April 30th 2023 and is no longer being maintained. Use the version switcher on the top left of this page to select documentation for a supported version of TYPO3.

Need more time before upgrading? You can purchase Extended Long Term Support (ELTS) for TYPO3 v10 here: TYPO3 ELTS.

Broadcast Channels¶

It is 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 must 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');
    }
 }