[TASK] Improve FlashMessages ViewHelper page

Documentation/Global/FlashMessages.rst

@@ -7,77 +7,110 @@
 FlashMessages ViewHelper `<f:flashMessages>`
 ============================================
 
+This ViewHelper renders the `Flash messages <https://docs.typo3.org/permalink/t3coreapi:flash-messages-api>`_
+(if there are any) as an unsorted list.
+
+..  figure:: /Images/FlashMessageExamples.png
+    :alt: Screenshot of two flash message one with success and one with warning severity
+
+    Example for the output of flash messages in an Extbase plugin
+
 ..  typo3:viewhelper:: flashMessages
-    :display: tags,description,gitHubLink,arguments
+    :display: tags,gitHubLink
     :source: ../Global.json
+    :noindex:
 
-..  _typo3-fluid-flashmessages-example:
+..  contents:: Table of contents
 
-Examples
-========
+..  _typo3-fluid-flashmessages-example-simple:
 
-Simple
-------
+Quick start: Simple flash message output
+========================================
 
-::
+You can use the following tag within any Extbase template:
 
-   <f:flashMessages />
+..  code-block:: html
+    :caption: packages/my_extension/Resources/Private/Templates/Something/DoSomething.html
 
-A list of flash messages.
+    <f:flashMessages />
 
-TYPO3 core style
-----------------
+It displays the flash messages with a standard bootstrap compatible layout.
 
-::
+..  _typo3-fluid-flashmessages-extbase:
 
-   <f:flashMessages />
+Adding and displaying flash messages in Extbase
+===============================================
 
-Output::
+Within an Extbase `controller <https://docs.typo3.org/permalink/t3coreapi:extbase-action-controller>`_
+(extending :php-short:`\TYPO3\CMS\Extbase\Mvc\Controller\ActionController`) you
+can call method `addFlashMessage()` to add flash messages to the message queue:
 
-   <div class="typo3-messages">
-      <div class="alert alert-info">
-         <div class="alert-inner">
-            <div class="alert-icon">
-               <span class="icon-emphasized">
-                  <span class="t3js-icon icon icon-size-small icon-state-default icon-actions-info" data-identifier="actions-info">
-                     <span class="icon-markup">
-                        <svg class="icon-color"><use xlink:href="/typo3/sysext/core/Resources/Public/Icons/T3Icons/sprites/actions.svg#actions-info"></use></svg>
-                     </span>
-                  </span>
-               </span>
-            </div>
-            <div class="alert-content">
-               <div class="alert-title">Info - Title for Info message</div>
-               <p class="alert-message">Message text here.</p>
-            </div>
-         </div>
-      </div>
-   </div>
+..  literalinclude:: _FlashMessages/_MyController.php
+    :caption: packages/my_extension/Classes/Controller/MyController.php
 
-Output flash messages as a description list
--------------------------------------------
+As mentioned above, they will be displayed when a `<f:flashMessages>` is displayed within any action
+of the same controller:
 
-::
+..  literalinclude:: _FlashMessages/_DemonstrateFlashMessages.html
+    :caption: packages/my_extension/Resources/Private/Templates/My/DemonstrateFlashMessages.html
 
-   <f:flashMessages as="flashMessages">
-      <dl class="messages">
-         <f:for each="{flashMessages}" as="flashMessage">
-            <dt>{flashMessage.code}</dt>
-            <dd>{flashMessage.message}</dd>
-         </f:for>
-      </dl>
-   </f:flashMessages>
+If you want to display the flash messages in any place outside of the controller
+you can use the identifier `extbase.flashmessages.<pluginNamespace>`, for example:
+
+..  literalinclude:: _FlashMessages/_SomeForm.html
+    :caption: packages/my_extension/Resources/Private/Templates/Other/SomeForm.html
+
+..  _typo3-fluid-flashmessages-queueIdentifier:
+
+Using a specific flash message queue in plain classes
+=====================================================
+
+When you use the FlashMessages ViewHelper outside of the Extbase context,
+supplying the :ref:`queueIdentifier <t3viewhelper:viewhelper-argument-typo3-cms-fluid-viewhelpers-flashmessagesviewhelper-queueidentifier>`
+is mandatory.
+
+When you add a message manually to the queue, you can specify an arbitrary
+identifier:
+
+..  code-block:: php
+
+    // private \TYPO3\CMS\Core\Messaging\FlashMessageService $flashMessageService;
 
-Output::
+    $messageQueue = $this->flashMessageService->getMessageQueueByIdentifier('myQueue');
 
-   <dl class="messages">
-      <dt>1013</dt>
-      <dd>Some Warning Message.</dd>
-  </dl>
+You can then display messages of only this one queue using the identifier:
 
-Using a specific queue
-----------------------
+..  code-block:: html
 
-::
+    <f:flashMessages queueIdentifier="myQueue" />
 
-   <f:flashMessages queueIdentifier="myQueue" />
+..  _typo3-fluid-flashmessages-example:
+..  _typo3-fluid-flashmessages-example-custom:
+
+Output flash messages with a custom layout
+==========================================
+
+Using the argument :ref:`as <t3viewhelper:viewhelper-argument-typo3-cms-fluid-viewhelpers-flashmessagesviewhelper-as>`
+you can receive all flash messages in a variable and then handle the rendering
+yourself within the `<f:flashMessages>` tag:
+
+..  code-block:: html
+    :caption: packages/my_extension/Resources/Private/Templates/Something/DoSomething.html
+
+    <f:flashMessages as="flashMessages">
+      <dl class="messages">
+        <f:for each="{flashMessages}" as="flashMessage">
+          <dt>{flashMessage.code}</dt>
+          <dd>{flashMessage.message}</dd>
+        </f:for>
+      </dl>
+    </f:flashMessages>
+
+..  _typo3-fluid-flashmessages-arguments:
+
+Argument of the FlashMessages ViewHelper
+========================================
+
+..  typo3:viewhelper:: flashMessages
+    :display: arguments-only
+    :source: ../Global.json

Documentation/Global/_FlashMessages/_DemonstrateFlashMessages.html

@@ -0,0 +1,4 @@
+<f:layout name="MyLayout"/>
+<f:section name="Content">
+    <f:flashMessages />
+</f:section>

Documentation/Global/_FlashMessages/_MyController.php

@@ -0,0 +1,18 @@
+<?php
+declare(strict_types=1);
+
+namespace MyVendor\MyExtension\Controller;
+
+use Psr\Http\Message\ResponseInterface;
+use TYPO3\CMS\Core\Type\ContextualFeedbackSeverity;
+use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;
+
+class MyController extends ActionController
+{
+    public function demonstrateFlashMessagesAction(): ResponseInterface
+    {
+        $this->addFlashMessage('This is a success message.');
+        $this->addFlashMessage('This is a warning.', 'Warning Headline', ContextualFeedbackSeverity::WARNING);
+        return $this->htmlResponse();
+    }
+}

Documentation/Global/_FlashMessages/_SomeForm.html

@@ -0,0 +1,4 @@
+<f:layout name="MyLayout"/>
+<f:section name="Content">
+    <f:flashMessages queueIdentifier="extbase.flashmessages.tx_myextension_myplugin"/>
+</f:section>