[FEATURE] Unify module button bar

[TYPO3IncTeam]

ℹ️ View this commit on Github
👥 Authored by Oliver Bartsch bo@cedev.de
✔️ Merged by Oli Bartsch bo@cedev.de

Commit message

[FEATURE] Unify module button bar

This unifies the module button bar across all backend
modules by automatically adding reload and shortcut
buttons in consistent positions.

Reload and shortcut buttons now always appear on the
right side of the button bar, ensuring they are always the
last two buttons regardless of what other buttons are added
by controllers or event listeners.

The shortcut button now uses a simplified API via
DocHeaderComponent::setShortcutContext() instead of requiring
manual button creation, and preserves full context (e.g., the
specific site, page, or record being edited) with appropriate
labels in the bookmark bar.

All core backend module controllers have been migrated to
use the new automatic button system, establishing a
consistent pattern throughout TYPO3.

Furthermore, the shortcut button does also now
preserve context like the site settings, a user
is currently editing and also uses a corresponding
label in the bookmark bar.

The site configuration and site settings editing
view uses a button to link to each other. This
button is basically the same as the "edit whole
record" button, known from FormEngine. This button
is therefore now aligned to use the "pencil"
icon and to be placed on the left side.

Resolves: #108008
Releases: main
Change-Id: I43ed7281844e72c558cf887ea9ca6862f96330ce
Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/91446
Reviewed-by: Lina Wolf 112@linawolf.de
Tested-by: Lina Wolf 112@linawolf.de
Reviewed-by: Jasmina Ließmann typo3@minapok.eu
Tested-by: Oli Bartsch bo@cedev.de
Tested-by: core-ci typo3@b13.com
Reviewed-by: Oli Bartsch bo@cedev.de
Tested-by: Jasmina Ließmann typo3@minapok.eu

➕ Added files

14.0/Deprecation-108008-ManualShortcutButtonCreation.rst

..  include:: /Includes.rst.txt

..  _deprecation-108008-1762896168:

======================================================
Deprecation: #108008 - Manual shortcut button creation
======================================================

See :issue:`108008`

Description
===========

Manually creating and adding :php:`ShortcutButton` instances to the button bar
is deprecated and will trigger a deprecation warning.

Controllers should use the new :php:`DocHeaderComponent::setShortcutContext()`
method instead, which automatically creates and positions the shortcut button.

Impact
======

Controllers that manually create and add :php:`ShortcutButton` to the button bar
will trigger a deprecation warning. The button will still work as expected.

Affected installations
======================

Installations with custom backend modules that manually create shortcut buttons.

Migration
=========

Replace manual shortcut button creation with the new API:

**Before**:

..  code-block:: php

    $shortcutButton = $this->componentFactory->createShortcutButton()
        ->setRouteIdentifier('my_module')
        ->setDisplayName('My Module')
        ->setArguments(['id' => $pageId]);
    $view->addButtonToButtonBar($shortcutButton);

**After**:

..  code-block:: php

    $view->getDocHeaderComponent()->setShortcutContext(
        routeIdentifier: 'my_module',
        displayName: 'My Module',
        arguments: ['id' => $pageId]
    );

..  index:: Backend, PHP-API, PartiallyScanned, ext:backend

14.0/Feature-108008-AutomaticReloadAndShortcutButtonsInBackendModules.rst

..  include:: /Includes.rst.txt

..  _feature-108008-1762896168:

===========================================================================
Feature: #108008 - Automatic reload and shortcut buttons in backend modules
===========================================================================

See :issue:`108008`

Description
===========

Backend modules now automatically get reload and shortcut buttons added to their
document header, ensuring consistent display across all backend modules.

Previously, controllers manually added these buttons with varying group numbers,
leading to inconsistent positioning. Now, buttons always appear on the right
side, ensuring they are always the last two buttons regardless of what other
buttons are added.

Controllers provide shortcut information using the new
:php:`DocHeaderComponent::setShortcutContext()` method:

..  code-block:: php

    $view->getDocHeaderComponent()->setShortcutContext(
        routeIdentifier: 'site_configuration.edit',
        displayName: sprintf('Edit site: %s', $siteIdentifier),
        arguments: ['site' => $siteIdentifier]
    );

Buttons are automatically added during rendering before the PSR-14
:php:`ModifyButtonBarEvent` is dispatched, allowing event listeners to modify
or remove them if needed.

Controllers can disable automatic buttons if custom behavior is required:

..  code-block:: php

    $view->getDocHeaderComponent()->disableAutomaticReloadButton();
    $view->getDocHeaderComponent()->disableAutomaticShortcutButton();

Impact
======

Reload and shortcut buttons now appear consistently at the same position across
all backend modules, providing a predictable user experience.

Controllers no longer need to manually create these buttons, reducing boilerplate
code. Use :php:`setShortcutContext()` to provide shortcut information and
remove manual button creation, see :ref:`deprecation-108008-1762896168`.

**Before**:

..  code-block:: php

    $reloadButton = $this->componentFactory->createReloadButton($uri);
    $view->addButtonToButtonBar($reloadButton, ButtonBar::BUTTON_POSITION_RIGHT, 3);

    $shortcutButton = $this->componentFactory->createShortcutButton()
        ->setRouteIdentifier('my_module')
        ->setDisplayName('My Module')
        ->setArguments(['id' => $pageId]);
    $view->addButtonToButtonBar($shortcutButton);

**After**:

..  code-block:: php

    // Set shortcut context only
    $view->getDocHeaderComponent()->setShortcutContext(
        routeIdentifier: 'my_module',
        displayName: 'My Module',
        arguments: ['id' => $pageId]
    );

.. index:: Backend, PHP-API, ext:backend