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..3ad72d8 --- /dev/null +++ b/Documentation/Global/Form/_codesnippets/_CommentController.php @@ -0,0 +1,39 @@ + '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.