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

Changed in version 12.0

The RequireJS module TYPO3/CMS/Backend/BroadcastService has been migrated to the ES6 module @typo3/backend/broadcast-service.js. See also ES6 in the TYPO3 Backend.

Any backend module may send a message using the @typo3/backend/broadcast-service.js ES6 module.

The payload of such a 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.

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

Example code:

EXT:my_broadcast_extension/Resources/Public/JavaScript/my-broadcast-service.js

import BroadcastService from "@typo3/backend/broadcast-service.js";

class MyBroadcastService {
  constructor() {
    const payload = {
      componentName: 'my_extension',
      eventName: 'my_event',
      hello: 'world',
      foo: ['bar', 'baz']
    };
    BroadcastService.post(payload);
  }
}
export default new MyBroadcastService();

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:

EXT:my_extension/Resources/Public/JavaScript/my-event-handler.js

class MyEventHandler {
  constructor() {
    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
  }
}
export default new MyEventHandler();

See also

Hook into $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['typo3/backend.php']['constructPostProcess'] to load a custom \TYPO3\CMS\Backend\Controller\BackendController hook that loads the event handler's JavaScript.

Example code:

EXT:my_extension/ext_localconf.php

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

EXT:my_extension/Classes/Hooks/BackendControllerHook.php

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Hooks;

use TYPO3\CMS\Core\Page\PageRenderer;

final class BackendControllerHook
{
    public function __construct(
        private readonly PageRenderer $pageRenderer,
    ) {}

    public function registerClientSideEventHandler(): void
    {
        $this->pageRenderer->loadJavaScriptModule(
            '@myvendor/my-extension/event-handler.js',
        );
        $this->pageRenderer->addInlineLanguageLabelFile(
            'EXT:my_extension/Resources/Private/Language/locallang_slug_service.xlf',
        );
    }
}

EXT:my_extension/Configuration/Services.yaml

services:
  _defaults:
    autowire: true
    autoconfigure: true
    public: false

  MyVendor\MyExtension\Hooks\BackendControllerHook:
    public: true