Breaking: #93093 - Rework Shortcut PHP API

See forge#93093

Description

The Shortcut PHP API used to store the full URL of the shortcut target in the sys_be_shortcuts table. It turned out that this is not working well, but error-prone and laborious. For example, all created shortcuts are automatically invalid as soon as the corresponding module changed its route path. Furthermore the url column included the token which was actually never used but regenerated on every link generation, e.g. when reloading the backend. Since even the initial returnUrl was stored in the database, a shortcut which linked to FormEngine has returned to this initial url.

All these characteristics oppose the introduction of speaking urls for the TYPO3 backend. Therefore, the internal handling and registration of the Shortcut PHP API was reworked.

A shortcut record does now not longer store the full url of the shortcut target but instead only the modules route identifier and the necessary arguments (parameters) for the URL.

The fields module_name and url of the sys_be_shortcuts table have been replaced with:

  • route - Contains the route identifier of the module to link to
  • arguments - Contains all necessary arguments (parameters) for the link as JSON encoded string

The arguments field not longer stores any of the following parameters:

  • route
  • token
  • returnUrl

Shortcuts are usually created by the JavaScript function TYPO3.ShortcutMenu.createShortcut() which performs an AJAX call to ShortcutController->addAction(). The parameter signature of the JavaScript function has been changed and the addAction() method does now feature an additional result string missingRoute, in case no routeIdentifier was provided in the AJAX call.

The parameter signature changed as followed:

// Old signature:
public createShortcut(
   moduleName: string,
   url: string,
   confirmationText: string,
   motherModule: string,
   shortcutButton: JQuery,
   displayName: string,
)

// New signature:
public createShortcut(
   routeIdentifier: string,
   routeArguments: string,
   displayName: string,
   confirmationText: string,
   shortcutButton: JQuery,
)
Copied!

The \TYPO3\CMS\Backend\Template\Components\Buttons\Action\ShortcutButton API for generating such links now provides a new public method setRouteIdentifier() which replaces the deprecated setModuleName() method. See Deprecation: #93093 - MethodName in Shortcut PHP API for all deprecations done during the rework.

Impact

Directly calling TYPO3.ShortcutMenu.createShortcut() with the old parameter signature will result in a JavaScript error.

Already created shortcuts won't be available prior to running the provided upgrade wizard.

The columns module_name and url have been removed. Directly querying these columns will raise a doctrine dbal exception.

Affected Installations

Installations with created shortcuts.

Installations with custom extensions directly calling TYPO3.ShortcutMenu.createShortcut() with the old parameter signature.

Installations with custom extensions, directly using the database columns module_name and url or relying on them being filled.

Installations with custom extensions using deprecated functionality of the Shortcut PHP API.

Migration

Update the database schema (only "Add fields to tables") and run the shortcutRecordsMigration upgrade wizard either in the install tool or on CLI with ./typo3/sysext/core/bin/typo3 upgrade:run shortcutRecordsMigration. Remove the unused module_name and url columns only after running the wizard.

Change any call to TYPO3.ShortcutMenu.createShortcut() to use the new parameter signature.

Migrate custom extension code to use route and arguments instead of module_name and url.

Migrate any call to deprecated functionality of the Shortcut PHP API.