From 1223cc01fa0fca126e3acb0ae68f9dff668fa2b8 Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Mon, 17 Mar 2025 14:19:10 +0100 Subject: [PATCH 1/2] [TASK] Update form ViewHelper page * Use realistic examples together with the corresponding controllers * Warn that it cannot be used without Extbase anymore * Write section about security, content translated and shortened from https://www.typo3lexikon.de/typo3-tutorials/core/systemextensions/fluid/viewhelper/ Releases: main, 13.4, 12.4 --- Documentation/Global/Form/Index.rst | 90 +++++++++++++++---- .../Global/Form/_codesnippets/Comment.php | 19 ++++ .../Form/_codesnippets/_CommentController.php | 38 ++++++++ .../Form/_codesnippets/_CommentForm.html | 16 ++++ .../_codesnippets/_PlainParameterForm.html | 9 ++ .../Form/_codesnippets/_SearchController.php | 17 ++++ .../_Includes/_ArbitraryArguments.rst.txt | 4 + .../_Includes/_ExtbaseFormViewHelpers.rst.txt | 7 ++ 8 files changed, 182 insertions(+), 18 deletions(-) create mode 100644 Documentation/Global/Form/_codesnippets/Comment.php create mode 100644 Documentation/Global/Form/_codesnippets/_CommentController.php create mode 100644 Documentation/Global/Form/_codesnippets/_CommentForm.html create mode 100644 Documentation/Global/Form/_codesnippets/_PlainParameterForm.html create mode 100644 Documentation/Global/Form/_codesnippets/_SearchController.php create mode 100644 Documentation/_Includes/_ArbitraryArguments.rst.txt create mode 100644 Documentation/_Includes/_ExtbaseFormViewHelpers.rst.txt diff --git a/Documentation/Global/Form/Index.rst b/Documentation/Global/Form/Index.rst index c0c2972..de86877 100644 --- a/Documentation/Global/Form/Index.rst +++ b/Documentation/Global/Form/Index.rst @@ -9,38 +9,92 @@ Form ViewHelper `` .. typo3:viewhelper:: form :source: /Global.json - :display: tags,description,gitHubLink,arguments + :display: tags,description,gitHubLink + :noindex: + +.. include:: /_Includes/_ExtbaseFormViewHelpers.rst.txt + +.. contents:: Table of contents .. _typo3-fluid-form-example: -Examples -======== +Array parameter passed to Extbase controller action +=================================================== + +For example a very simplified search form could look like this: + +.. literalinclude:: _codesnippets/_PlainParameterForm.html + :caption: packages/my_extension/Resources/Private/Templates/Search/SearchForm.html + +The `Extbase controller `_ +action could for example look like this: + +.. literalinclude:: _codesnippets/_SearchController.php + :caption: packages/my_extension/Classes/Controller/SearchController.php + +.. _typo3-fluid-form-example-property: + +Property mapping - using the form with a model +============================================== + +In most cases you will use the f:form ViewHelper with +`Extbase models `_ or +data objects. + +For example, user could add a comment in such a form: -A complex form with a specified encoding type ---------------------------------------------- +.. literalinclude:: _codesnippets/_CommentForm.html + :caption: packages/my_extension/Resources/Private/Templates/Comment/_CommentForm.html -Form with enctype set:: +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 +:ref:`object ` +to pass any data the object might already contain to the ViewHelper. - ... +By using the argument "property" on the form input elements the properties of +the model are automatically bound to the input elements. -A Form which should render a domain object ------------------------------------------- +The controller could look like this: -Binding a domain object to a form:: +.. literalinclude:: _codesnippets/_CommentController.php + :caption: packages/my_extension/Classes/Controller/CommentController.php - - - - +If the model is not valid (see `Validation `_) +Extbase will automatically refer the request back to the referring action +(here commentFormAction()). By passing the object with the non-validated object +to the view again, the user can see their faulty inputs and correct them instead +of seeing an empty form. -This automatically inserts the value of ``{customer.name}`` inside the -textarea and adjusts the name of the textarea accordingly. +.. _typo3-fluid-form-security: + +Security in Fluid forms +======================= + +Fluid automatically adds a hidden field to forms, including an `__hmac` +value. This value lists all allowed fields. If fields are added or +removed via attacks, Extbase detects the mismatch and blocks submission. + +Form fields can be grouped in an array for efficient processing. The +receiving action maps the data to a model, where validation occurs if +rules are defined. Only valid data is passed to the action and stored in +the database. + +.. _typo3-fluid-form-arguments: + +Arguments of the form ViewHelper +================================ + +.. include:: /_Includes/_ArbitraryArguments.rst.txt + +.. typo3:viewhelper:: form + :source: /Global.json + :display: arguments-only .. _typo3-fluid-form-viewhelpers: -ViewHelpers to be used within the form ViewHelper -================================================= +ViewHelpers for form input elements +=================================== .. toctree:: :titlesonly: diff --git a/Documentation/Global/Form/_codesnippets/Comment.php b/Documentation/Global/Form/_codesnippets/Comment.php new file mode 100644 index 0000000..d50f89d --- /dev/null +++ b/Documentation/Global/Form/_codesnippets/Comment.php @@ -0,0 +1,19 @@ + 'EmailAddress'])] + protected string $email = ''; + + #[Validate(['validator' => 'StringLength', 'options' => ['maximum' => 500]])] + protected string $content = ''; + + // Getters and setters ... +} diff --git a/Documentation/Global/Form/_codesnippets/_CommentController.php b/Documentation/Global/Form/_codesnippets/_CommentController.php new file mode 100644 index 0000000..c78c2fa --- /dev/null +++ b/Documentation/Global/Form/_codesnippets/_CommentController.php @@ -0,0 +1,38 @@ + 'newComment'])] + public function commentFormAction(?Comment $newComment = null): ResponseInterface { + if ($newComment === null) { + $newComment = new Comment(); + $newComment->setDate(new \DateTime()); + } + // The assigned object will be used in argument object + $this->view->assign('newComment', $newComment); + return $this->htmlResponse(); + } + + public function createAction( + // This parameter must have the same name as argument `objectName` of f:form + Comment $comment, + ): ResponseInterface { + $this->commentRepository->add($comment); + $this->addFlashMessage('Comment was saved'); + return $this->redirect('show'); + } +} diff --git a/Documentation/Global/Form/_codesnippets/_CommentForm.html b/Documentation/Global/Form/_codesnippets/_CommentForm.html new file mode 100644 index 0000000..3311382 --- /dev/null +++ b/Documentation/Global/Form/_codesnippets/_CommentForm.html @@ -0,0 +1,16 @@ + + +
+ + +
+
+ + +
+
+ +
+ + diff --git a/Documentation/Global/Form/_codesnippets/_PlainParameterForm.html b/Documentation/Global/Form/_codesnippets/_PlainParameterForm.html new file mode 100644 index 0000000..4e8cfd1 --- /dev/null +++ b/Documentation/Global/Form/_codesnippets/_PlainParameterForm.html @@ -0,0 +1,9 @@ + +
+ + +
+
+ +
+ diff --git a/Documentation/Global/Form/_codesnippets/_SearchController.php b/Documentation/Global/Form/_codesnippets/_SearchController.php new file mode 100644 index 0000000..d841968 --- /dev/null +++ b/Documentation/Global/Form/_codesnippets/_SearchController.php @@ -0,0 +1,17 @@ +htmlResponse(); + } +} diff --git a/Documentation/_Includes/_ArbitraryArguments.rst.txt b/Documentation/_Includes/_ArbitraryArguments.rst.txt new file mode 100644 index 0000000..e3401e5 --- /dev/null +++ b/Documentation/_Includes/_ArbitraryArguments.rst.txt @@ -0,0 +1,4 @@ +.. admonition:: Allows arbitrary arguments + + This ViewHelper allows you to pass arbitrary arguments not defined below + directly to the HTML tag created. This includes custom `data-` arguments. diff --git a/Documentation/_Includes/_ExtbaseFormViewHelpers.rst.txt b/Documentation/_Includes/_ExtbaseFormViewHelpers.rst.txt new file mode 100644 index 0000000..96b646b --- /dev/null +++ b/Documentation/_Includes/_ExtbaseFormViewHelpers.rst.txt @@ -0,0 +1,7 @@ +.. attention:: + .. versionchanged:: 12.0 + The f:form ViewHelpers can only be used within the Extbase context. + + In a non-Extbase context, for example within a + `FLUIDTEMPLATE `_ + Use plain HTML `
` and `` tags. From df0d341a7607df268150289a0b267c83ca2f407d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stefan=20Fr=C3=B6mken?= Date: Tue, 18 Mar 2025 22:32:22 +0100 Subject: [PATCH 2/2] Update Documentation/Global/Form/_codesnippets/_CommentController.php --- Documentation/Global/Form/_codesnippets/_CommentController.php | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/Global/Form/_codesnippets/_CommentController.php b/Documentation/Global/Form/_codesnippets/_CommentController.php index c78c2fa..3ad72d8 100644 --- a/Documentation/Global/Form/_codesnippets/_CommentController.php +++ b/Documentation/Global/Form/_codesnippets/_CommentController.php @@ -17,7 +17,8 @@ public function __construct( ) {} #[IgnoreValidation(['argumentName' => 'newComment'])] - public function commentFormAction(?Comment $newComment = null): ResponseInterface { + public function commentFormAction(?Comment $newComment = null): ResponseInterface + { if ($newComment === null) { $newComment = new Comment(); $newComment->setDate(new \DateTime());