Skip to content

Commit 6e7c25d

Browse files
linawolfsfroemkenjw
linawolf
and
sfroemkenjw
authored
[TASK] Improve FlashMessages ViewHelper page (#102)
* [TASK] Improve FlashMessages ViewHelper page Releases: main, 13.4 * Apply suggestions from code review * Update FlashMessages.rst --------- Co-authored-by: Stefan Frömken <[email protected]>
1 parent 6a9a995 commit 6e7c25d

File tree

5 files changed

+112
-53
lines changed

5 files changed

+112
-53
lines changed

‎Documentation/Global/FlashMessages.rst‎

Lines changed: 86 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -7,77 +7,110 @@
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+
Quick start: Simple flash message output
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+
Adding 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+
As mentioned above, 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:
59+
60+
.. literalinclude:: _FlashMessages/_SomeForm.html
61+
:caption: packages/my_extension/Resources/Private/Templates/Other/SomeForm.html
62+
63+
.. _typo3-fluid-flashmessages-queueIdentifier:
64+
65+
Using a specific flash message queue in plain classes
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;
7078
71-
Output::
79+
$messageQueue = $this->flashMessageService->getMessageQueueByIdentifier('myQueue');
7280
73-
<dl class="messages">
74-
<dt>1013</dt>
75-
<dd>Some Warning Message.</dd>
76-
</dl>
81+
You can then display messages of only this one queue using the identifier:
7782

78-
Using a specific queue
79-
----------------------
83+
.. code-block:: html
8084

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

83-
<f:flashMessages queueIdentifier="myQueue" />
87+
.. _typo3-fluid-flashmessages-example:
88+
.. _typo3-fluid-flashmessages-example-custom:
89+
90+
Output flash messages with a custom layout
91+
==========================================
92+
93+
Using the argument :ref:`as <t3viewhelper:viewhelper-argument-typo3-cms-fluid-viewhelpers-flashmessagesviewhelper-as>`
94+
you can receive all flash messages in a variable and then handle the rendering
95+
yourself within the `<f:flashMessages>` tag:
96+
97+
.. code-block:: html
98+
:caption: packages/my_extension/Resources/Private/Templates/Something/DoSomething.html
99+
100+
<f:flashMessages as="flashMessages">
101+
<dl class="messages">
102+
<f:for each="{flashMessages}" as="flashMessage">
103+
<dt>{flashMessage.code}</dt>
104+
<dd>{flashMessage.message}</dd>
105+
</f:for>
106+
</dl>
107+
</f:flashMessages>
108+
109+
.. _typo3-fluid-flashmessages-arguments:
110+
111+
Argument of the FlashMessages ViewHelper
112+
========================================
113+
114+
.. typo3:viewhelper:: flashMessages
115+
:display: arguments-only
116+
: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)