DocHeaderComponent 

DocHeaderComponent API 

It has the following methods:

class DocHeaderComponent

Fully qualified name

\TYPO3\CMS\Backend\Template\Components\DocHeaderComponent

Document header component for backend modules.

This component manages the header area of backend module views, providing: - Breadcrumb navigation (via BreadcrumbContext) - Button bar for action buttons (save, close, delete, etc.) - Drop-down menus for module-specific actions

The component can be enabled or disabled to control visibility of the entire document header. It integrates with the ModuleTemplate to provide a consistent header across all backend modules.

Usage in a controller:

public function __construct(
    protected readonly ComponentFactory $componentFactory,
) }

public function myAction(): ResponseInterface
{
    $view = $this->moduleTemplateFactory->create($request);
    $docHeader = $view->getDocHeaderComponent();

    // Set breadcrumb for a page
    $docHeader->setPageBreadcrumb($pageInfo);

    // Add action buttons using ComponentFactory
    $buttonBar = $docHeader->getButtonBar();
    $saveButton = $this->componentFactory->createSaveButton('editform');
    $buttonBar->addButton($saveButton, ButtonBar::BUTTON_POSITION_LEFT, 1);
}

Copied!

setBreadcrumbContext(?\TYPO3\CMS\Backend\Breadcrumb\BreadcrumbContext $breadcrumbContext)

Sets the breadcrumb context for rendering.

This is the main API for providing breadcrumb information.

For common scenarios, use the convenience methods instead: - setPageBreadcrumb() for page records - setRecordBreadcrumb() for any record - setResourceBreadcrumb() for files or folders

param $breadcrumbContext

The breadcrumb context

setPageBreadcrumb(array $pageRecord)

Sets breadcrumb from a page record array.

Example: $view->getDocHeaderComponent()->setPageBreadcrumb($pageInfo);

param $pageRecord

The page record array (must contain 'uid')

setRecordBreadcrumb(string $table, int $uid)

Sets breadcrumb for editing a record.

Example: $view->getDocHeaderComponent()->setRecordBreadcrumb('tt_content', 123);

param $table

The table name

param $uid

The record UID

setResourceBreadcrumb(\TYPO3\CMS\Core\Resource\ResourceInterface $resource)

Sets breadcrumb for any resource (file or folder).

Example: $view->getDocHeaderComponent()->setResourceBreadcrumb($file); $view->getDocHeaderComponent()->setResourceBreadcrumb($folder);

param $resource

The resource (file or folder)

addBreadcrumbSuffixNode(\TYPO3\CMS\Backend\Dto\Breadcrumb\BreadcrumbNode $node)

Adds a suffix node to the current breadcrumb context.

Suffix nodes are appended after the main breadcrumb trail and are useful for: - Indicating "Create New" actions - Showing "Edit Multiple" states - Adding custom contextual information

Example:

$docHeader->setPageBreadcrumb($pageInfo); $docHeader->addBreadcrumbSuffixNode( new BreadcrumbNode( identifier: 'new', label: 'Create New Content Element', icon: 'actions-add' ) );

Note: This creates or modifies the breadcrumb context. If you need to build a complete context, use BreadcrumbFactory instead.

param $node

The node to append

getMenuRegistry()

Returns the menu registry for adding drop-down menus to the document header.

Returns

TYPO3CMSBackendTemplateComponentsMenuRegistry

getButtonBar()

Returns the button bar for adding action buttons to the document header.

The button bar supports multiple button positions (left, right) and groups to organize buttons logically.

Returns

TYPO3CMSBackendTemplateComponentsButtonBar

isEnabled()

Determines whether this component is enabled and should be rendered.

When disabled, the entire document header (including breadcrumbs, buttons, and menus) will not be displayed in the backend module.

Returns

bool

enable()

Enables this component for rendering.

disable()

Disables this component to prevent rendering.

setLanguageSelector(?\TYPO3\CMS\Backend\Template\Components\ComponentInterface $component)

param $component

the component

getLanguageSelector()

Returns

?TYPO3CMSBackendTemplateComponentsComponentInterface

setShortcutContext(string $routeIdentifier, string $displayName, array $arguments = [])

Sets the context for the automatic shortcut button.

Controllers can use this method to provide shortcut information without manually creating and adding the shortcut button. The button will be automatically added to the button bar in the correct position.

Example:

$docHeader->setShortcutContext('site_configuration.edit', sprintf('Edit site: %s', $siteIdentifier), ['site' => $siteIdentifier]);

param $routeIdentifier

The route identifier for the shortcut

param $displayName

The display name shown in the bookmark list

param $arguments

Optional arguments to include in the shortcut URL, default: []

disableAutomaticReloadButton()

Disables the automatic reload button for this module.

Use this if your module needs custom reload behavior or should not have a reload button at all.

disableAutomaticShortcutButton()

Disables the automatic shortcut button for this module.

Use this if your module should not have a shortcut button.

docHeaderContent(?\Psr\Http\Message\ServerRequestInterface $request)

Returns the complete document header content as an array for rendering.

This method aggregates all components (buttons, breadcrumbs) into a structured array that can be consumed by the Fluid template rendering the backend module layout.

The returned array structure: - 'enabled': Whether the document header should be rendered - 'buttons': Array of button configurations from the button bar - 'breadcrumb': Breadcrumb trail data from the breadcrumb context - 'languageSelector': Language Selector

param $request

the request

Returns

array

Setting the breadcrumb of a backend module 

The breadcrumb shows where the user is, and each of its nodes links back to that level. A module tells the DocHeaderComponent what the user is working on:

setPageBreadcrumb(array $pageRecord)

The page of the given page record, with the path through the page tree.

setRecordBreadcrumb(string $table, int $uid)

A record of any table, on the page it belongs to.

setResourceBreadcrumb(ResourceInterface $resource)

A file or folder, with the path through its file storage.

addBreadcrumbSuffixNode(BreadcrumbNode $node)

An additional node at the end, for example for the current action. A node without a URL is not clickable, which suits the current item.

The nodes are built from the current request, so they keep the module and its current action.

Layout of the backend module header 

The module header consists of two rows:

• The top row has the breadcrumb on the left and, if the module provides one, a language selector on the right.

• The second row is the button bar. On the left, it starts with the dropdown of the module actions from button group 0, followed by the module buttons. The functional buttons are on the right, such as Reload or Bookmark.

  

Adding module actions and a language selector to the module header 

makeDocHeaderModuleMenu() of ModuleTemplate adds a dropdown consisting of the submodules of the current module. If there is only one, it is hidden.

setLanguageSelector() of DocHeaderComponent places a dropdown in the top right corner. If setShowActiveLabelText(true) , the dropdown shows the selected item, for example "English", as its text, and screen readers announce the label and the selected item, "Language: English":

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use TYPO3\CMS\Backend\Routing\UriBuilder;
use TYPO3\CMS\Backend\Template\Components\ComponentFactory;
use TYPO3\CMS\Backend\Template\ModuleTemplate;
use TYPO3\CMS\Backend\Template\ModuleTemplateFactory;
use TYPO3\CMS\Core\Authentication\BackendUserAuthentication;
use TYPO3\CMS\Core\Imaging\IconFactory;
use TYPO3\CMS\Core\Site\Entity\Site;

final readonly class ConferenceController
{
  public function __construct(
    private ModuleTemplateFactory $moduleTemplateFactory,
    private ComponentFactory $componentFactory,
    private IconFactory $iconFactory,
    private UriBuilder $uriBuilder,
  ) {}

  public function handleRequest(
    ServerRequestInterface $request,
  ): ResponseInterface {
    $view = $this->moduleTemplateFactory->create($request);
    $pageId = (int)($request->getQueryParams()['id'] ?? 0);
    $languageId = (int)($request->getQueryParams()['language'] ?? 0);

    // Dropdown of the module's submodules, shown if there are several
    $view->makeDocHeaderModuleMenu(['id' => $pageId]);

    $this->addLanguageSelector($view, $request, $pageId, $languageId);

    return $view->renderResponse('Conference/Index');
  }

  private function addLanguageSelector(
    ModuleTemplate $view,
    ServerRequestInterface $request,
    int $pageId,
    int $activeLanguageId,
  ): void {
    /** @var Site $site */
    $site = $request->getAttribute('site');
    $languageSelector = $this->componentFactory->createDropDownButton()
        ->setLabel('Language')
        ->setShowLabelText(true)
        // Show the selected language as the button text
        ->setShowActiveLabelText(true);

    $languages = $site->getAvailableLanguages(
      $this->getBackendUser(),
      false,
      $pageId,
    );
    foreach ($languages as $language) {
      $url = $this->uriBuilder->buildUriFromRoute(
        'my_extension_conference',
        ['id' => $pageId, 'language' => $language->getLanguageId()],
      );
      $languageSelector->addItem(
        $this->componentFactory->createDropDownRadio()
            ->setHref((string)$url)
            ->setLabel($language->getTitle())
            ->setIcon(
              $this->iconFactory->getIcon($language->getFlagIdentifier()),
            )
            ->setActive($language->getLanguageId() === $activeLanguageId),
      );
    }

    $view->getDocHeaderComponent()->setLanguageSelector($languageSelector);
  }

  private function getBackendUser(): BackendUserAuthentication
  {
    return $GLOBALS['BE_USER'];
  }
}

Example: build a module header with buttons and a menu 

The following example is extracted from the example Extbase extension t3docs/blog-example . See the complete source code at t3doc/blog-example (GitHub).

We use the DocHeaderComponent to register buttons and a menu to the module header.

<?php

use Psr\Http\Message\ServerRequestInterface;
use TYPO3\CMS\Backend\Template\ModuleTemplate;
use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;

class BackendController extends ActionController
{
  private function modifyDocHeaderComponent(
    ModuleTemplate $view,
    string &$context,
  ): void {
    $menu = $this->buildMenu($view, $context);
    $view->getDocHeaderComponent()->getMenuRegistry()->addMenu($menu);

    $buttonBar = $view->getDocHeaderComponent()->getButtonBar();
    $this->addButtons($buttonBar);

    $pageRecord = $this->getPageRecord();
    if (is_array($pageRecord)) {
      $view->getDocHeaderComponent()->setPageBreadcrumb($pageRecord);
    }
  }

  protected function initializeModuleTemplate(
    ServerRequestInterface $request,
  ): ModuleTemplate {
    $view = $this->moduleTemplateFactory->create($request);

    $context = '';
    $this->modifyDocHeaderComponent($view, $context);
    $view->setFlashMessageQueue($this->getFlashMessageQueue());
    $title = $this->getLanguageService()
        ->sL('blog_example.module.mod:mlang_tabs_tab');
    $view->setTitle($title, $context);

    return $view;
  }
}