Flash messages API¶
Instantiate a flash message¶
Creating a flash message is achieved by instantiating an object
of class \TYPO3\CMS\Core\Messaging\FlashMessage
:
use TYPO3\CMS\Core\Messaging\FlashMessage;
use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\CMS\Core\Type\ContextualFeedbackSeverity;
// FlashMessage($message, $title = '', $severity = ContextualFeedbackSeverity::OK, $storeInSession = false)
$message = GeneralUtility::makeInstance(FlashMessage::class,
'My message text',
'Message Header',
ContextualFeedbackSeverity::WARNING,
true
);
$message
- The text of the message
$title
- [optional] the header
$severity
- [optional] the severity (default:
ContextualFeedbackSeverity::OK
) $storeInSession
- [optional]
true
: store in the session orfalse
: store only in the\TYPO3\CMS\Core\Messaging\FlashMessageQueue
object. Storage in the session should be used if you need the message to be still present after a redirection (default:false
).
Flash messages severities¶
Changed in version 13.0
The previous class constants of \TYPO3\CMS\Core\Messaging\FlashMessage
have been removed with TYPO3 v13.0.
The severity is defined by using the
\TYPO3\CMS\Core\Type\ContextualFeedbackSeverity
enumeration:
ContextualFeedbackSeverity::NOTICE
for notificationsContextualFeedbackSeverity::INFO
for information messagesContextualFeedbackSeverity::OK
for success messagesContextualFeedbackSeverity::WARNING
for warningsContextualFeedbackSeverity::ERROR
for errors
Add a flash message to the queue¶
In backend modules you can then make that message appear on top of the module after a page refresh or the rendering of the next page request or render it on your own where ever you want.
In this example the FlashMessageService
(TYPO3\CMS\Core\Messaging\FlashMessageService
)
is used to add a flash message at the top a module:
use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\CMS\Core\Messaging\FlashMessageService;
$flashMessageService = GeneralUtility::makeInstance(FlashMessageService::class);
$messageQueue = $flashMessageService->getMessageQueueByIdentifier();
$messageQueue->addMessage($message);
The message is added to the queue and then the template class calls
\TYPO3\CMS\Core\Messaging\FlashMessageQueue::renderFlashMessages()
which renders all
messages from the queue as inline flash messages. Here's how such a message looks like in a module:
This shows flash messages with 2 types of rendering mechanisms:
- several flash messages are displayed inline
- and an additional flash message ("Record count") is rendered as top-right notification (which automatically disappear after a short delay).
New in version 12.0
FlashMessageQueue::NOTIFICATION_QUEUE
has been added in TYPO3 v12 to
provide a simple mechanism to add flash messages (from PHP code) to be
displayed as notifications on the top-right edge of the backend. Previously,
this had to be implemented in JavaScript (e.g. Notification.success()
),
which is also still possible, see JavaScript-based flash messages (Notification API).
Use the FlashMessageQueue::NOTIFICATION_QUEUE
to submit a flash message
as top-right notifications, instead of inline:
use TYPO3\CMS\Core\Messaging\FlashMessage;
use TYPO3\CMS\Core\Messaging\FlashMessageQueue;
use TYPO3\CMS\Core\Messaging\FlashMessageService;
use TYPO3\CMS\Core\Type\ContextualFeedbackSeverity;
use TYPO3\CMS\Core\Utility\GeneralUtility;
$flashMessageService = GeneralUtility::makeInstance(FlashMessageService::class);
$notificationQueue = $flashMessageService->getMessageQueueByIdentifier(
FlashMessageQueue::NOTIFICATION_QUEUE
);
$flashMessage = GeneralUtility::makeInstance(
FlashMessage::class,
'I am a message rendered as notification',
'Hooray!',
ContextualFeedbackSeverity::OK
);
$notificationQueue->enqueue($flashMessage);
The recommended way to show flash messages is to use the Fluid ViewHelper <f:flashMessages />
.
This ViewHelper works in any context because it use the FlashMessageRendererResolver
class
to find the correct renderer for the current context.