Skip to content

Commit 8449d47

Browse files
linawolflinawolf
committed
[TASK] Improve FlashMessages ViewHelper page
Releases: main, 13.4
1 parent 6a9a995 commit 8449d47

File tree

5 files changed

+116
-52
lines changed

5 files changed

+116
-52
lines changed

‎Documentation/Global/FlashMessages.rst‎

Lines changed: 90 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -7,77 +7,115 @@
77
FlashMessages ViewHelper `<f:flashMessages>`
88
============================================
99

10+
This ViewHelper renders the `Flash messages <https://docs.typo3.org/permalink/t3coreapi:flash-messages-api>`_
11+
(if there are any) as an unsorted list.
12+
13+
.. figure:: /Images/FlashMessageExamples.png
14+
:alt: Screenshot of two flash message one with success and one with warning severity
15+
16+
Example for the output of flash messages in an Extbase plugin
17+
1018
.. typo3:viewhelper:: flashMessages
11-
:display: tags,description,gitHubLink,arguments
19+
:display: tags,gitHubLink
1220
:source: ../Global.json
21+
:noindex:
1322

14-
.. _typo3-fluid-flashmessages-example:
23+
.. contents:: Table of contents
1524

16-
Examples
17-
========
25+
.. _typo3-fluid-flashmessages-example-simple:
1826

19-
Simple
20-
------
27+
Simple flash message output (Extbase only)
28+
==========================================
2129

22-
::
30+
You can use the following tag within any Extbase template:
2331

24-
<f:flashMessages />
32+
.. code-block:: html
33+
:caption: packages/my_extension/Resources/Private/Templates/Something/DoSomething.html
2534

26-
A list of flash messages.
35+
<f:flashMessages />
2736

28-
TYPO3 core style
29-
----------------
37+
It displays the flash messages with a standard bootstrap compatible layout.
3038

31-
::
39+
.. _typo3-fluid-flashmessages-extbase:
3240

33-
<f:flashMessages />
41+
Using and displaying flash messages in Extbase
42+
==============================================
3443

35-
Output::
44+
Within an Extbase `controller <https://docs.typo3.org/permalink/t3coreapi:extbase-action-controller>`_
45+
(extending :php-short:`\TYPO3\CMS\Extbase\Mvc\Controller\ActionController`) you
46+
can call method `addFlashMessage()` to add flash messages to the message queue:
3647

37-
<div class="typo3-messages">
38-
<div class="alert alert-info">
39-
<div class="alert-inner">
40-
<div class="alert-icon">
41-
<span class="icon-emphasized">
42-
<span class="t3js-icon icon icon-size-small icon-state-default icon-actions-info" data-identifier="actions-info">
43-
<span class="icon-markup">
44-
<svg class="icon-color"><use xlink:href="/typo3/sysext/core/Resources/Public/Icons/T3Icons/sprites/actions.svg#actions-info"></use></svg>
45-
</span>
46-
</span>
47-
</span>
48-
</div>
49-
<div class="alert-content">
50-
<div class="alert-title">Info - Title for Info message</div>
51-
<p class="alert-message">Message text here.</p>
52-
</div>
53-
</div>
54-
</div>
55-
</div>
48+
.. literalinclude:: _FlashMessages/_MyController.php
49+
:caption: packages/my_extension/Classes/Controller/MyController.php
5650

57-
Output flash messages as a description list
58-
-------------------------------------------
51+
They will be displayed when a `<f:flashMessages>` is displayed within any action
52+
of the same controller:
5953

60-
::
54+
.. literalinclude:: _FlashMessages/_DemonstrateFlashMessages.html
55+
:caption: packages/my_extension/Resources/Private/Templates/My/DemonstrateFlashMessages.html
6156

62-
<f:flashMessages as="flashMessages">
63-
<dl class="messages">
64-
<f:for each="{flashMessages}" as="flashMessage">
65-
<dt>{flashMessage.code}</dt>
66-
<dd>{flashMessage.message}</dd>
67-
</f:for>
68-
</dl>
69-
</f:flashMessages>
57+
If you want to display the flash messages in any place outside of the controller
58+
you can use the identifier `extbase.flashmessages.<pluginNamespace>`, for example:
7059

71-
Output::
60+
.. literalinclude:: _FlashMessages/_SomeForm.html
61+
:caption: packages/my_extension/Resources/Private/Templates/Other/SomeForm.html
7262

73-
<dl class="messages">
74-
<dt>1013</dt>
75-
<dd>Some Warning Message.</dd>
76-
</dl>
63+
.. _typo3-fluid-flashmessages-queueIdentifier:
7764

7865
Using a specific queue
79-
----------------------
66+
======================
67+
68+
When you use the FlashMessages ViewHelper outside of the Extbase context,
69+
supplying the :ref:`queueIdentifier <t3viewhelper:viewhelper-argument-typo3-cms-fluid-viewhelpers-flashmessagesviewhelper-queueidentifier>`
70+
is mandatory.
71+
72+
When you add a message manually to the queue, you can specify an arbitrary
73+
identifier:
74+
75+
.. code-block:: php
76+
77+
// private \TYPO3\CMS\Core\Messaging\FlashMessageService flashMessageService;
78+
79+
$messageQueue = $this->flashMessageService->getMessageQueueByIdentifier('myQueue');
80+
81+
You can then display messages of only this one queue using the identifier:
82+
83+
.. code-block:: html
8084

81-
::
85+
<f:flashMessages queueIdentifier="myQueue" />
8286

83-
<f:flashMessages queueIdentifier="myQueue" />
87+
.. tip::
88+
In Extbase controllers the `queueIdentifier` is
89+
`extbase.flashmessages.<pluginNamespace>` by default, see also
90+
`Using and displaying flash messages in Extbase <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-flashmessages-extbase>`_.
91+
92+
.. _typo3-fluid-flashmessages-example:
93+
.. _typo3-fluid-flashmessages-example-custom:
94+
95+
Output flash messages with a custom layout
96+
==========================================
97+
98+
Using the argument :ref:`as <t3viewhelper:viewhelper-argument-typo3-cms-fluid-viewhelpers-flashmessagesviewhelper-as>`
99+
you can receive all flash messages in a variable and then handle the rendering
100+
yourself within the `<f:flashMessages>` tag:
101+
102+
.. code-block:: html
103+
:caption: packages/my_extension/Resources/Private/Templates/Something/DoSomething.html
104+
105+
<f:flashMessages as="flashMessages">
106+
<dl class="messages">
107+
<f:for each="{flashMessages}" as="flashMessage">
108+
<dt>{flashMessage.code}</dt>
109+
<dd>{flashMessage.message}</dd>
110+
</f:for>
111+
</dl>
112+
</f:flashMessages>
113+
114+
.. _typo3-fluid-flashmessages-arguments:
115+
116+
Argument of the FlashMessages ViewHelper
117+
========================================
118+
119+
.. typo3:viewhelper:: flashMessages
120+
:display: arguments-only
121+
:source: ../Global.json

‎Documentation/Global/_FlashMessages/_DemonstrateFlashMessages.html‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
<f:layout name="MyLayout"/>
2+
<f:section name="Content">
3+
<f:flashMessages />
4+
</f:section>

‎Documentation/Global/_FlashMessages/_MyController.php‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<?php
2+
declare(strict_types=1);
3+
4+
namespace MyVendor\MyExtension\Controller;
5+
6+
use Psr\Http\Message\ResponseInterface;
7+
use TYPO3\CMS\Core\Type\ContextualFeedbackSeverity;
8+
use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;
9+
10+
class MyController extends ActionController
11+
{
12+
public function demonstrateFlashMessagesAction(): ResponseInterface
13+
{
14+
$this->addFlashMessage('This is a success message.');
15+
$this->addFlashMessage('This is a warning. ', 'Warning Headline', ContextualFeedbackSeverity::WARNING);
16+
return $this->htmlResponse();
17+
}
18+
}

‎Documentation/Global/_FlashMessages/_SomeForm.html‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
<f:layout name="MyLayout"/>
2+
<f:section name="Content">
3+
<f:flashMessages queueIdentifier="extbase.flashmessages.tx_myextension_myplugin"/>
4+
</f:section>

‎Documentation/Images/FlashMessageExamples.png‎

4.02 KB
Loading

0 commit comments

Comments
 (0)