[TASK] Update f:form.submit ViewHelper page (#117)

* [TASK] Update f:form.submit ViewHelper page

Releases: main, 13.4

* Apply suggestions from code review

---------

Co-authored-by: Garvin Hicking <[email protected]>
(cherry picked from commit 27f3c54)

Author: linawolf

Documentation/Global/Form/Index.rst

@@ -44,7 +44,7 @@ data objects.
 For example, user could add a comment in such a form:
 
 ..  literalinclude:: _codesnippets/_CommentForm.html
-    :caption: packages/my_extension/Resources/Private/Templates/Comment/_CommentForm.html
+    :caption: packages/my_extension/Resources/Private/Templates/Comment/CommentForm.html
 
 The Extbase Controller action displaying the form then creates the Domain object
 and passes it to the view. In the Fluid template above we use argument

Documentation/Global/Form/Submit.rst

@@ -9,31 +9,85 @@ Form.submit ViewHelper `<f:form.submit>`
 
 ..  typo3:viewhelper:: form.submit
     :source: ../../Global.json
-    :display: tags,description,gitHubLink,arguments
+    :display: tags
+    :noindex:
+
+Creates a submit button (`<input type="submit"...>`) within a
+`Form ViewHelper <f:form> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-form>`_.
+
+..  note::
+    If you you need a `<button>` with extended HTML content, use the
+    `Form.button ViewHelper <f:form.button> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-form-button>`_
+    instead.
+
+..  typo3:viewhelper:: form.submit
+    :source: ../../Global.json
+    :display: gitHubLink
+    :noindex:
+
+..  contents:: Table of contents
 
 ..  _typo3-fluid-form-submit-example:
 
-Examples
-========
+A Fluid form with a single submit button
+========================================
+
+You can use the `<f:form.submit value="Submit!">` button within an Extbase
+form to display a `<input type="submit" value="Submit!">` button.
+
+When the user clicks the button, the action specified by the surrounding
+`<f:form> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-form>`_
+is called.
+
+..  tabs::
 
-Defaults
---------
+    ..  group-tab:: Fluid
 
-::
+        ..  literalinclude:: _codesnippets/_FormSubmit.html
+            :caption: packages/my_extension/Resources/Private/Templates/Comment/Edit.html
 
-   <f:form.submit value="Send Mail" />
+    ..  group-tab:: Controller
 
-Output::
+        The controller action can then look like this:
 
-   <input type="submit" />
+        ..  literalinclude:: _codesnippets/_SubmitController.php
+            :caption: packages/my_extension/Classes/Controller/CommentController.php
 
-Dummy content for template preview
-----------------------------------
+..  _typo3-fluid-form-submit-example-multiple:
 
-::
+A Fluid form with multiple submit buttons
+=========================================
 
-   <f:form.submit name="mySubmit" value="Send Mail"><button>dummy button</button></f:form.submit>
+When you want to offer different actions, it can be helpful to use multiple
+submit buttons with different labels:
 
-Output::
+..  tabs::
 
-   <input type="submit" name="mySubmit" value="Send Mail" />
+    ..  group-tab:: Fluid
+
+        ..  literalinclude:: _codesnippets/_FormSubmitMultiple.html
+            :caption: packages/my_extension/Resources/Private/Templates/Comment/Edit.html
+
+    ..  group-tab:: Controller
+
+        The controller action can then look like this:
+
+        ..  literalinclude:: _codesnippets/_SubmitMultipleController.php
+            :caption: packages/my_extension/Classes/Controller/CommentController.php
+
+..  note::
+    All rendered buttons will be rendered as `<input type="submit"...>`.
+    If you need a button with a different type than "submit", use the
+    `Form.button ViewHelper <f:form.button> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-form-button>`_
+    instead.
+
+..  _typo3-fluid-form-submit-arguments:
+
+Arguments of the form.submit ViewHelper
+=======================================
+
+..  include:: /_Includes/_ArbitraryArguments.rst.txt
+
+..  typo3:viewhelper:: form.submit
+    :source: /Global.json
+    :display: arguments-only

Documentation/Global/Form/_codesnippets/_FormSubmit.html

@@ -0,0 +1,8 @@
+<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
+      data-namespace-typo3-fluid="true">
+    <f:form action="submit" controller="Comment" objectName="comment" object="{comment}" method="post">
+        <label for="tx-blogexample-content">Message:</label>
+        <f:form.textarea property="content" id="tx-blogexample-content" rows="8" cols="46"/>
+        <f:form.submit value="Submit"/>
+    </f:form>
+</html>

Documentation/Global/Form/_codesnippets/_FormSubmitMultiple.html

@@ -0,0 +1,10 @@
+<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
+      data-namespace-typo3-fluid="true">
+    <f:form action="submit" controller="MyController" objectName="comment" object="{comment}" method="post">
+        <label for="tx-blogexample-content">Message:</label>
+        <f:form.textarea property="content" id="tx-blogexample-content" rows="8" cols="46"/>
+        <f:form.submit name="submitButton" value="Submit"/>
+        <f:form.submit name="cancelButton" value="Cancel"/>
+        <f:form.submit name="spellingButton" value="Check spelling"/>
+    </f:form>
+</html>

Documentation/Global/Form/_codesnippets/_SubmitController.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MyVendor\MyExtension\Controller;
+
+use Psr\Http\Message\ResponseInterface;
+use T3docs\BlogExample\Domain\Model\Comment;
+use T3docs\BlogExample\Domain\Repository\CommentRepository;
+use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;
+
+class CommentController extends ActionController
+{
+    public function __construct(
+        protected readonly CommentRepository $commentRepository,
+    ) {}
+
+    public function submitAction(Comment $comment): ResponseInterface
+    {
+        $this->commentRepository->update($comment);
+        $this->addFlashMessage('Your comment was saved');
+        return $this->redirect('show');
+    }
+
+    // Other actions
+}

Documentation/Global/Form/_codesnippets/_SubmitMultipleController.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MyVendor\MyExtension\Controller;
+
+use Psr\Http\Message\ResponseInterface;
+use T3docs\BlogExample\Domain\Model\Comment;
+use T3docs\BlogExample\Domain\Repository\CommentRepository;
+use TYPO3\CMS\Core\Type\ContextualFeedbackSeverity;
+use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;
+
+class CommentController extends ActionController
+{
+    public function __construct(
+        protected readonly CommentRepository $commentRepository,
+    ) {}
+
+    public function submitAction(
+        Comment $comment,
+        bool $cancelButton = false,
+        bool $spellingButton = false,
+    ): ResponseInterface {
+        if ($cancelButton) {
+            $this->addFlashMessage(
+                'Your comment was NOT saved, you pressed the cancel button',
+                'Attention',
+                ContextualFeedbackSeverity::WARNING,
+            );
+            return $this->redirect('show');
+        }
+        if ($spellingButton) {
+            if (!$this->mySpellCheckService->check($comment->getMessage())) {
+                $this->addFlashMessage('There are spelling errors. ');
+            }
+            return $this->redirect('edit', null, null, ['comment' => $comment]);
+        }
+        // Form was submitted by submit button or for example by JavaScript
+        $this->commentRepository->update($comment);
+        $this->addFlashMessage('Your comment was saved');
+        return $this->redirect('show');
+    }
+
+    // Other actions
+}