diff --git a/Documentation/Global/Form/Checkbox.rst b/Documentation/Global/Form/Checkbox.rst index b81b9f5..c4e403a 100644 --- a/Documentation/Global/Form/Checkbox.rst +++ b/Documentation/Global/Form/Checkbox.rst @@ -9,46 +9,224 @@ Form.checkbox ViewHelper `` .. typo3:viewhelper:: form.checkbox :source: ../../Global.json - :display: tags,description,gitHubLink,arguments + :display: tags,description,gitHubLink + :noindex: + +.. contents:: Table of contents + +.. _typo3-fluid-form-checkbox-single: + +Single checkboxes +================= + +A single checkbox is usually mapped to a boolean property or controller +argument. + +However due to how checkboxes work in HTML a non-checked checkbox does not +appear in the request sent by the form submission. Therefore properties and arguments +need to default to `false`. They will then be set to `true` if the checkbox +was checked. + +While the :ref:`value ` +does not play a role when you are working with a checkbox, the argument must still +be supplied. .. _typo3-fluid-form-checkbox-example: -Examples -======== +Single optional checkbox tied to an action argument +-------------------------------------------------- + +Checkboxes in HTML work a little different from other input fields in that +multiple or none at all can be checked. + +Fluid outputs a normal HTML ``_ +and some of the pitfalls also apply here. Especially a check box that is not +sends no argument to the request. + +.. tabs:: + + .. group-tab:: Fluid + + .. literalinclude:: _codesnippets/_CheckboxOptional.html + :caption: packages/my_extension/Resources/Private/Templates/Comment/Newsletter.html + + .. group-tab:: Controller + + Then the controller action can then look like this: + + .. literalinclude:: _codesnippets/_CheckboxController.php + :caption: packages/my_extension/Classes/Controller/NewsletterController.php + +.. note:: + If a checkbox is not checked it sends NO argument as opposed to a text input + with no text entered. Therefore in the Extbase action you **must** supply + a default for the argument if non-checked fields should be allowed. + +.. _typo3-fluid-form-checkbox-example-preselected: + +The checkbox should already by checked / preselected +---------------------------------------------------- + +.. code-block:: html + + + +You can also use a variable to determine whether the field should be +checked: + +.. code-block:: html + + + +.. note:: + When you work with `Property mapping `_ + the checkbox is automatically preselected if the model's property evalutes to `true`. + +.. _typo3-fluid-form-checkbox-property: + +Property mapping - domain model property bound to single checkbox +----------------------------------------------------------------- + +If you are using `the form with a model `_ +you can use the argument :ref:`property ` +to map the checkbox to a property of your domain model or data object: + +.. tabs:: + + .. group-tab:: Fluid + + .. literalinclude:: _codesnippets/_CheckboxProperty.html + :caption: packages/my_extension/Resources/Private/Templates/Newsletter/SomeForm.html + + .. group-tab:: Controller + + Then the controller action can look like this: -Simple one ----------- + .. literalinclude:: _codesnippets/_CheckboxModelController.php + :caption: packages/my_extension/Classes/Controller/NewsletterController.php -:: + .. group-tab:: Model - + An unchecked checkbox results in the property not being set. It should + therefore default to `false`. -Output:: + .. literalinclude:: _codesnippets/_CheckboxModelUser.php + :caption: packages/my_extension/Classes/Domain/Model/User.php - +If the property in the domain model is `true` when the form is displayed, the +checkbox is preselected. -Preselect ---------- +.. _typo3-fluid-form-checkbox-multiple: -:: +Multiple checkboxes for the same property +========================================= - +Unlike other input elements, multiple checkboxes can be used for the same +property or action argument. -Output:: +In this case they share the same :ref:`name ` +or property binding :ref:`property ` +but have distinct :ref:`values `. - +If you are working with action arguments, :ref:`multiple ` +must be set. -Depending on bound ``object`` to surrounding :ref:`f:form `. +.. _typo3-fluid-form-checkbox-multiple-action: -Bind to object property ------------------------ +Multiple checkboxes mapped to an array in a controller action +------------------------------------------------------------- -:: +Multiple checkboxes are usually mapped to an `array`. It would however be possible, for example, +to map them to an integer using binaries or such. - +Therefore when working with multiple checkboxes and arrays, you have to tell +Extbase how to map the data from the request to your controller action in an +`initialize` action. -Output:: +.. tabs:: - + .. group-tab:: Fluid -Depending on property ``interests``. + .. literalinclude:: _codesnippets/_CheckboxMultiple.html + :caption: packages/my_extension/Resources/Private/Templates/Newsletter/SomeForm.html + + .. group-tab:: Controller + + Then the controller action can look like this: + + .. literalinclude:: _codesnippets/_CheckboxMultipleController.php + :caption: packages/my_extension/Classes/Controller/NewsletterController.php + +.. note:: + See class :php:`\TYPO3\CMS\Extbase\Property\TypeConverter\ArrayConverter` + for details on mapping arrays. + +.. _typo3-fluid-form-checkbox-multiple-property: + +Property mapping of multiple checkboxes +--------------------------------------- + +When working with multiple checkboxes mapped to the property of an Extbase model +or data object, the same +:ref:`property ` +is used for all checkboxes to be mapped to that property. + +.. note:: + An example is still missing. **You** can help by providing an example. + + Click the "report issue" button above and hand in your examples. + +.. _typo3-fluid-form-checkbox-multiple-independent: + +Multiple checkboxes for multiple independent properties +======================================================= + +When multiple checkboxes should be used independently they must have unique +:ref:`name ` +properties to map to multiple action arguments or unique +:ref:`property ` +values to bind to multiple properties. + +.. _typo3-fluid-form-checkbox-mandatory: + +Mandatory checkboxes - require a checkbox to be set +=================================================== + +On the browser side you can use the `HTML 5 "required" Attribute `_. +As the `` ViewHelper allows arbitrary arguments, using +the `required` property is possible even though it is not listed. + +.. tabs:: + + .. group-tab:: Fluid + + .. literalinclude:: _codesnippets/_CheckboxRequired.html + :caption: packages/my_extension/Resources/Private/Templates/Newsletter/SomeForm.html + + .. group-tab:: Controller + + Then the controller action can then look like this: + + .. literalinclude:: _codesnippets/_CheckboxModelController.php + :caption: packages/my_extension/Classes/Controller/NewsletterController.php + + .. group-tab:: Model + + You should also validate the model for the property to be true: + + .. literalinclude:: _codesnippets/_CheckboxModelUserRequired.php + :caption: packages/my_extension/Classes/Domain/Model/User.php + +If the server side validation on the model fails, the request is forwarded to +the originating request with an error message. + +.. _typo3-fluid-form-checkbox-arguments: + +Arguments +========= + +.. include:: /_Includes/_ArbitraryArguments.rst.txt + +.. typo3:viewhelper:: form.checkbox + :source: ../../Global.json + :display: arguments-only diff --git a/Documentation/Global/Form/_codesnippets/_CheckboxController.php b/Documentation/Global/Form/_codesnippets/_CheckboxController.php new file mode 100644 index 0000000..c6e8f98 --- /dev/null +++ b/Documentation/Global/Form/_codesnippets/_CheckboxController.php @@ -0,0 +1,22 @@ +htmlResponse(); + } +} diff --git a/Documentation/Global/Form/_codesnippets/_CheckboxModelController.php b/Documentation/Global/Form/_codesnippets/_CheckboxModelController.php new file mode 100644 index 0000000..c499f5b --- /dev/null +++ b/Documentation/Global/Form/_codesnippets/_CheckboxModelController.php @@ -0,0 +1,21 @@ +isOrderNewsletter()) { + // TODO: Newsletter ordering + } + return $this->htmlResponse(); + } +} diff --git a/Documentation/Global/Form/_codesnippets/_CheckboxModelUser.php b/Documentation/Global/Form/_codesnippets/_CheckboxModelUser.php new file mode 100644 index 0000000..7e5adaa --- /dev/null +++ b/Documentation/Global/Form/_codesnippets/_CheckboxModelUser.php @@ -0,0 +1,23 @@ +orderNewsletter; + } + + public function setOrderNewsletter(bool $orderNewsletter): void + { + $this->orderNewsletter = $orderNewsletter; + } + +} diff --git a/Documentation/Global/Form/_codesnippets/_CheckboxModelUserRequired.php b/Documentation/Global/Form/_codesnippets/_CheckboxModelUserRequired.php new file mode 100644 index 0000000..559c50f --- /dev/null +++ b/Documentation/Global/Form/_codesnippets/_CheckboxModelUserRequired.php @@ -0,0 +1,27 @@ + 'Boolean', + 'options' => ['is' => true], + ])] + protected bool $consentGiven = false; + + public function isConsentGiven(): bool + { + return $this->consentGiven; + } + + public function setConsentGiven(bool $consentGiven): void + { + $this->consentGiven = $consentGiven; + } +} diff --git a/Documentation/Global/Form/_codesnippets/_CheckboxMultiple.html b/Documentation/Global/Form/_codesnippets/_CheckboxMultiple.html new file mode 100644 index 0000000..d8eea80 --- /dev/null +++ b/Documentation/Global/Form/_codesnippets/_CheckboxMultiple.html @@ -0,0 +1,9 @@ + + +
+ + +
+
+
+
diff --git a/Documentation/Global/Form/_codesnippets/_CheckboxMultipleController.php b/Documentation/Global/Form/_codesnippets/_CheckboxMultipleController.php new file mode 100644 index 0000000..041383e --- /dev/null +++ b/Documentation/Global/Form/_codesnippets/_CheckboxMultipleController.php @@ -0,0 +1,34 @@ +htmlResponse(); + } + public function initializeOrderNewsletterAction() + { + if ($this->request->hasArgument('orderNewsletters')) { + $this->arguments['orderNewsletters'] + ->getPropertyMappingConfiguration() + ->setTypeConverterOption( + ArrayConverter::class, + ArrayConverter::CONFIGURATION_DELIMITER, + ',', + ); + } + } +} diff --git a/Documentation/Global/Form/_codesnippets/_CheckboxOptional.html b/Documentation/Global/Form/_codesnippets/_CheckboxOptional.html new file mode 100644 index 0000000..b438945 --- /dev/null +++ b/Documentation/Global/Form/_codesnippets/_CheckboxOptional.html @@ -0,0 +1,9 @@ + +
+ + +
+
+ +
+
diff --git a/Documentation/Global/Form/_codesnippets/_CheckboxProperty.html b/Documentation/Global/Form/_codesnippets/_CheckboxProperty.html new file mode 100644 index 0000000..d20f4d8 --- /dev/null +++ b/Documentation/Global/Form/_codesnippets/_CheckboxProperty.html @@ -0,0 +1,9 @@ + +
+ + +
+
+ +
+
diff --git a/Documentation/Global/Form/_codesnippets/_CheckboxRequired.html b/Documentation/Global/Form/_codesnippets/_CheckboxRequired.html new file mode 100644 index 0000000..61ca6f5 --- /dev/null +++ b/Documentation/Global/Form/_codesnippets/_CheckboxRequired.html @@ -0,0 +1,10 @@ + + +
+ + +
+
+ +
+