[BUGFIX] Fix several typos in php comments
[Packages/TYPO3.CMS.git] / typo3 / sysext / fluid / Classes / ViewHelpers / Form / SelectViewHelper.php
index f434629..c850d0c 100644 (file)
@@ -15,65 +15,77 @@ namespace TYPO3\CMS\Fluid\ViewHelpers\Form;
  */
 
 /**
- * This view helper generates a <select> dropdown list for the use with a form.
+ * This ViewHelper generates a :html:`<select>` dropdown list for the use with a form.
  *
- * = Basic usage =
+ * Basic usage
+ * ===========
  *
- * The most straightforward way is to supply an associative array as the "options" parameter.
+ * The most straightforward way is to supply an associative array as the ``options`` parameter.
  * The array key is used as option key, and the value is used as human-readable name.
  *
- * <code title="Basic usage">
- * <f:form.select name="paymentOptions" options="{payPal: 'PayPal International Services', visa: 'VISA Card'}" />
- * </code>
+ * Basic usage::
  *
- * = Pre-select a value =
+ *    <f:form.select name="paymentOptions" options="{payPal: 'PayPal International Services', visa: 'VISA Card'}" />
+ *
+ * Pre select a value
+ * ------------------
+ *
+ * To pre select a value, set ``value`` to the option key which should be selected.
+ * Default value::
+ *
+ *    <f:form.select name="paymentOptions" options="{payPal: 'PayPal International Services', visa: 'VISA Card'}" value="visa" />
  *
- * To pre-select a value, set "value" to the option key which should be selected.
- * <code title="Default value">
- * <f:form.select name="paymentOptions" options="{payPal: 'PayPal International Services', visa: 'VISA Card'}" value="visa" />
- * </code>
  * Generates a dropdown box like above, except that "VISA Card" is selected.
  *
- * If the select box is a multi-select box (multiple="1"), then "value" can be an array as well.
+ * If the select box is a multi-select box :html:`multiple="1"`, then "value" can be an array as well.
+ *
+ * Custom options and option group rendering
+ * -----------------------------------------
  *
- * = Custom options and option group rendering =
+ * Child nodes can be used to create a completely custom set of
+ * :html:`<option>` and :html:`<optgroup>` tags in a way compatible with the
+ * HMAC generation.
+ * To do so, leave out the ``options`` argument and use child ViewHelpers:
  *
- * Child nodes can be used to create a completely custom set of ``<option>`` and ``<optgroup>`` tags in a way compatible with
- * the HMAC generation. To do so, leave out the ``options`` argument and use child ViewHelpers:
- * <code title="Custom options and optgroup">
- * <f:form.select name="myproperty">
- *     <f:form.select.option value="1">Option one</f:form.select.option>
- *     <f:form.select.option value="2">Option two</f:form.select.option>
- *     <f:form.select.optgroup>
- *         <f:form.select.option value="3">Grouped option one</f:form.select.option>
- *         <f:form.select.option value="4">Grouped option twi</f:form.select.option>
- *     </f:form.select.optgroup>
- * </f:form.select>
- * </code>
- * Note: do not use vanilla ``<option>`` or ``<optgroup>`` tags! They will invalidate the HMAC generation!
+ * Custom options and optgroup::
  *
- * = Usage on domain objects =
+ *    <f:form.select name="myproperty">
+ *       <f:form.select.option value="1">Option one</f:form.select.option>
+ *       <f:form.select.option value="2">Option two</f:form.select.option>
+ *       <f:form.select.optgroup>
+ *          <f:form.select.option value="3">Grouped option one</f:form.select.option>
+ *          <f:form.select.option value="4">Grouped option twi</f:form.select.option>
+ *       </f:form.select.optgroup>
+ *    </f:form.select>
  *
- * If you want to output domain objects, you can just pass them as array into the "options" parameter.
- * To define what domain object value should be used as option key, use the "optionValueField" variable. Same goes for optionLabelField.
- * If neither is given, the Identifier (UID/uid) and the __toString() method are tried as fallbacks.
+ * .. note::
+ *    Do not use vanilla :html:`<option>` or :html:`<optgroup>` tags!
+ *    They will invalidate the HMAC generation!
  *
- * If the optionValueField variable is set, the getter named after that value is used to retrieve the option key.
- * If the optionLabelField variable is set, the getter named after that value is used to retrieve the option value.
+ * Usage on domain objects
+ * -----------------------
  *
- * If the prependOptionLabel variable is set, an option item is added in first position, bearing an empty string or -
- * If provided, the value of the prependOptionValue variable as value.
+ * If you want to output domain objects, you can just pass them as array into the ``options`` parameter.
+ * To define what domain object value should be used as option key, use the ``optionValueField`` variable. Same goes for ``optionLabelField``.
+ * If neither is given, the Identifier (UID/uid) and the :php:`__toString()` method are tried as fallbacks.
  *
- * <code title="Domain objects">
- * <f:form.select name="users" options="{userArray}" optionValueField="id" optionLabelField="firstName" />
- * </code>
- * In the above example, the userArray is an array of "User" domain objects, with no array key specified.
+ * If the ``optionValueField`` variable is set, the getter named after that value is used to retrieve the option key.
+ * If the ``optionLabelField`` variable is set, the getter named after that value is used to retrieve the option value.
  *
- * So, in the above example, the method $user->getId() is called to retrieve the key, and $user->getFirstName() to retrieve the displayed value of each entry.
+ * If the ``prependOptionLabel`` variable is set, an option item is added in first position, bearing an empty string or -
+ * if provided, the value of the ``prependOptionValue`` variable as value.
  *
- * The "value" property now expects a domain object, and tests for object equivalence.
+ * Domain objects::
  *
- * @api
+ *    <f:form.select name="users" options="{userArray}" optionValueField="id" optionLabelField="firstName" />
+ *
+ * In the above example, the ``userArray`` is an array of "User" domain objects, with no array key specified.
+ *
+ * So, in the above example, the method :php:`$user->getId()` is called to
+ * retrieve the key, and :php:`$user->getFirstName()` to retrieve the displayed
+ * value of each entry.
+ *
+ * The ``value`` property now expects a domain object, and tests for object equivalence.
  */
 class SelectViewHelper extends \TYPO3\CMS\Fluid\ViewHelpers\Form\AbstractFormFieldViewHelper
 {
@@ -85,12 +97,10 @@ class SelectViewHelper extends \TYPO3\CMS\Fluid\ViewHelpers\Form\AbstractFormFie
     /**
      * @var mixed
      */
-    protected $selectedValue = null;
+    protected $selectedValue;
 
     /**
      * Initialize arguments.
-     *
-     * @api
      */
     public function initializeArguments()
     {
@@ -104,7 +114,7 @@ class SelectViewHelper extends \TYPO3\CMS\Fluid\ViewHelpers\Form\AbstractFormFie
         $this->registerArgument('optionLabelField', 'string', 'If specified, will call the appropriate getter on each object to determine the label.');
         $this->registerArgument('sortByOptionLabel', 'boolean', 'If true, List will be sorted by label.', false, false);
         $this->registerArgument('selectAllByDefault', 'boolean', 'If specified options are selected if none was set before.', false, false);
-        $this->registerArgument('errorClass', 'string', 'CSS class to set if there are errors for this view helper', false, 'f3-form-error');
+        $this->registerArgument('errorClass', 'string', 'CSS class to set if there are errors for this ViewHelper', false, 'f3-form-error');
         $this->registerArgument('prependOptionLabel', 'string', 'If specified, will provide an option at first position with the specified label.');
         $this->registerArgument('prependOptionValue', 'string', 'If specified, will provide an option at first position with the specified value.');
         $this->registerArgument('multiple', 'boolean', 'If set multiple options may be selected.', false, false);
@@ -115,15 +125,14 @@ class SelectViewHelper extends \TYPO3\CMS\Fluid\ViewHelpers\Form\AbstractFormFie
      * Render the tag.
      *
      * @return string rendered tag.
-     * @api
      */
     public function render()
     {
-        if ($this->arguments['required']) {
+        if (isset($this->arguments['required']) && $this->arguments['required']) {
             $this->tag->addAttribute('required', 'required');
         }
         $name = $this->getName();
-        if ($this->arguments['multiple']) {
+        if (isset($this->arguments['multiple']) && $this->arguments['multiple']) {
             $this->tag->addAttribute('multiple', 'multiple');
             $name .= '[]';
         }
@@ -136,15 +145,17 @@ class SelectViewHelper extends \TYPO3\CMS\Fluid\ViewHelpers\Form\AbstractFormFie
         // register field name for token generation.
         // in case it is a multi-select, we need to register the field name
         // as often as there are elements in the box
-        if ($this->arguments['multiple']) {
+        if (isset($this->arguments['multiple']) && $this->arguments['multiple']) {
             $content .= $this->renderHiddenFieldForEmptyValue();
-            for ($i = 0; $i < count($options); $i++) {
+            $optionsCount = count($options);
+            for ($i = 0; $i < $optionsCount; $i++) {
                 $this->registerFieldNameForFormTokenGeneration($name);
             }
             // save the parent field name so that any child f:form.select.option
             // tag will know to call registerFieldNameForFormTokenGeneration
+            // this is the reason why "self::class" is used instead of static::class (no LSB)
             $this->viewHelperVariableContainer->addOrUpdate(
-                static::class,
+                self::class,
                 'registerFieldNameForFormTokenGeneration',
                 $name
             );
@@ -152,13 +163,13 @@ class SelectViewHelper extends \TYPO3\CMS\Fluid\ViewHelpers\Form\AbstractFormFie
             $this->registerFieldNameForFormTokenGeneration($name);
         }
 
-        $this->viewHelperVariableContainer->addOrUpdate(static::class, 'selectedValue', $this->getSelectedValue());
+        $this->viewHelperVariableContainer->addOrUpdate(self::class, 'selectedValue', $this->getSelectedValue());
         $prependContent = $this->renderPrependOptionTag();
         $tagContent = $this->renderOptionTags($options);
         $childContent = $this->renderChildren();
-        $this->viewHelperVariableContainer->remove(static::class, 'selectedValue');
-        $this->viewHelperVariableContainer->remove(static::class, 'registerFieldNameForFormTokenGeneration');
-        if ($this->arguments['optionsAfterContent']) {
+        $this->viewHelperVariableContainer->remove(self::class, 'selectedValue');
+        $this->viewHelperVariableContainer->remove(self::class, 'registerFieldNameForFormTokenGeneration');
+        if (isset($this->arguments['optionsAfterContent']) && $this->arguments['optionsAfterContent']) {
             $tagContent = $childContent . $tagContent;
         } else {
             $tagContent .= $childContent;
@@ -223,7 +234,7 @@ class SelectViewHelper extends \TYPO3\CMS\Fluid\ViewHelpers\Form\AbstractFormFie
                         if (method_exists($key, '__toString')) {
                             $key = (string)$key;
                         } else {
-                            throw new \TYPO3\CMS\Fluid\Core\ViewHelper\Exception('Identifying value for object of class "' . get_class($value) . '" was an object.', 1247827428);
+                            throw new \TYPO3Fluid\Fluid\Core\ViewHelper\Exception('Identifying value for object of class "' . get_class($value) . '" was an object.', 1247827428);
                         }
                     }
                 } elseif ($this->persistenceManager->getIdentifierByObject($value) !== null) {
@@ -232,7 +243,7 @@ class SelectViewHelper extends \TYPO3\CMS\Fluid\ViewHelpers\Form\AbstractFormFie
                 } elseif (method_exists($value, '__toString')) {
                     $key = (string)$value;
                 } else {
-                    throw new \TYPO3\CMS\Fluid\Core\ViewHelper\Exception('No identifying value for object of class "' . get_class($value) . '" found.', 1247826696);
+                    throw new \TYPO3Fluid\Fluid\Core\ViewHelper\Exception('No identifying value for object of class "' . get_class($value) . '" found.', 1247826696);
                 }
                 if ($this->hasArgument('optionLabelField')) {
                     $value = \TYPO3\CMS\Extbase\Reflection\ObjectAccess::getPropertyPath($value, $this->arguments['optionLabelField']);
@@ -240,7 +251,7 @@ class SelectViewHelper extends \TYPO3\CMS\Fluid\ViewHelpers\Form\AbstractFormFie
                         if (method_exists($value, '__toString')) {
                             $value = (string)$value;
                         } else {
-                            throw new \TYPO3\CMS\Fluid\Core\ViewHelper\Exception('Label value for object of class "' . get_class($value) . '" was an object without a __toString() method.', 1247827553);
+                            throw new \TYPO3Fluid\Fluid\Core\ViewHelper\Exception('Label value for object of class "' . get_class($value) . '" was an object without a __toString() method.', 1247827553);
                         }
                     }
                 } elseif (method_exists($value, '__toString')) {
@@ -326,7 +337,7 @@ class SelectViewHelper extends \TYPO3\CMS\Fluid\ViewHelpers\Form\AbstractFormFie
      *
      * @param string $value value attribute of the option tag (will be escaped)
      * @param string $label content of the option tag (will be escaped)
-     * @param bool $isSelected specifies wheter or not to add selected attribute
+     * @param bool $isSelected specifies whether or not to add selected attribute
      * @return string the rendered option tag
      */
     protected function renderOptionTag($value, $label, $isSelected)