21ed9b4874cf4f4aaeb86f5de22a26fe2a646ecf
[Packages/TYPO3.CMS.git] / typo3 / sysext / fluid / Classes / ViewHelpers / Form / SelectViewHelper.php
1 <?php
2 namespace TYPO3\CMS\Fluid\ViewHelpers\Form;
3
4 /*
5 * This file is part of the TYPO3 CMS project.
6 *
7 * It is free software; you can redistribute it and/or modify it under
8 * the terms of the GNU General Public License, either version 2
9 * of the License, or any later version.
10 *
11 * For the full copyright and license information, please read the
12 * LICENSE.txt file that was distributed with this source code.
13 *
14 * The TYPO3 project - inspiring people to share!
15 */
16
17 /**
18 * This view helper generates a <select> dropdown list for the use with a form.
19 *
20 * = Basic usage =
21 *
22 * The most straightforward way is to supply an associative array as the "options" parameter.
23 * The array key is used as option key, and the value is used as human-readable name.
24 *
25 * <code title="Basic usage">
26 * <f:form.select name="paymentOptions" options="{payPal: 'PayPal International Services', visa: 'VISA Card'}" />
27 * </code>
28 *
29 * = Pre-select a value =
30 *
31 * To pre-select a value, set "value" to the option key which should be selected.
32 * <code title="Default value">
33 * <f:form.select name="paymentOptions" options="{payPal: 'PayPal International Services', visa: 'VISA Card'}" value="visa" />
34 * </code>
35 * Generates a dropdown box like above, except that "VISA Card" is selected.
36 *
37 * If the select box is a multi-select box (multiple="1"), then "value" can be an array as well.
38 *
39 * = Usage on domain objects =
40 *
41 * If you want to output domain objects, you can just pass them as array into the "options" parameter.
42 * To define what domain object value should be used as option key, use the "optionValueField" variable. Same goes for optionLabelField.
43 * If neither is given, the Identifier (UID/uid) and the __toString() method are tried as fallbacks.
44 *
45 * If the optionValueField variable is set, the getter named after that value is used to retrieve the option key.
46 * If the optionLabelField variable is set, the getter named after that value is used to retrieve the option value.
47 *
48 * If the prependOptionLabel variable is set, an option item is added in first position, bearing an empty string or -
49 * If provided, the value of the prependOptionValue variable as value.
50 *
51 * <code title="Domain objects">
52 * <f:form.select name="users" options="{userArray}" optionValueField="id" optionLabelField="firstName" />
53 * </code>
54 * In the above example, the userArray is an array of "User" domain objects, with no array key specified.
55 *
56 * 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.
57 *
58 * The "value" property now expects a domain object, and tests for object equivalence.
59 *
60 * @api
61 */
62 class SelectViewHelper extends \TYPO3\CMS\Fluid\ViewHelpers\Form\AbstractFormFieldViewHelper
63 {
64 /**
65 * @var string
66 */
67 protected $tagName = 'select';
68
69 /**
70 * @var mixed
71 */
72 protected $selectedValue = null;
73
74 /**
75 * Initialize arguments.
76 *
77 * @return void
78 * @api
79 */
80 public function initializeArguments()
81 {
82 parent::initializeArguments();
83 $this->registerUniversalTagAttributes();
84 $this->registerTagAttribute('size', 'string', 'Size of input field');
85 $this->registerTagAttribute('disabled', 'string', 'Specifies that the input element should be disabled when the page loads');
86 $this->registerArgument('options', 'array', 'Associative array with internal IDs as key, and the values are displayed in the select box', true);
87 $this->registerArgument('optionValueField', 'string', 'If specified, will call the appropriate getter on each object to determine the value.');
88 $this->registerArgument('optionLabelField', 'string', 'If specified, will call the appropriate getter on each object to determine the label.');
89 $this->registerArgument('sortByOptionLabel', 'boolean', 'If true, List will be sorted by label.', false, false);
90 $this->registerArgument('selectAllByDefault', 'boolean', 'If specified options are selected if none was set before.', false, false);
91 $this->registerArgument('errorClass', 'string', 'CSS class to set if there are errors for this view helper', false, 'f3-form-error');
92 $this->registerArgument('prependOptionLabel', 'string', 'If specified, will provide an option at first position with the specified label.');
93 $this->registerArgument('prependOptionValue', 'string', 'If specified, will provide an option at first position with the specified value.');
94 $this->registerArgument('multiple', 'boolean', 'If set multiple options may be selected.', false, false);
95 }
96
97 /**
98 * Render the tag.
99 *
100 * @return string rendered tag.
101 * @api
102 */
103 public function render()
104 {
105 $name = $this->getName();
106 if ($this->arguments['multiple']) {
107 $this->tag->addAttribute('multiple', 'multiple');
108 $name .= '[]';
109 }
110 $this->tag->addAttribute('name', $name);
111 $options = $this->getOptions();
112 if (empty($options)) {
113 $options = ['' => ''];
114 }
115 $this->tag->setContent($this->renderOptionTags($options));
116 $this->addAdditionalIdentityPropertiesIfNeeded();
117 $this->setErrorClassAttribute();
118 $content = '';
119 // register field name for token generation.
120 // in case it is a multi-select, we need to register the field name
121 // as often as there are elements in the box
122 if ($this->arguments['multiple']) {
123 $content .= $this->renderHiddenFieldForEmptyValue();
124 for ($i = 0; $i < count($options); $i++) {
125 $this->registerFieldNameForFormTokenGeneration($name);
126 }
127 } else {
128 $this->registerFieldNameForFormTokenGeneration($name);
129 }
130 $content .= $this->tag->render();
131 return $content;
132 }
133
134 /**
135 * Render the option tags.
136 *
137 * @param array $options the options for the form.
138 * @return string rendered tags.
139 */
140 protected function renderOptionTags($options)
141 {
142 $output = '';
143 if ($this->hasArgument('prependOptionLabel')) {
144 $value = $this->hasArgument('prependOptionValue') ? $this->arguments['prependOptionValue'] : '';
145 $label = $this->arguments['prependOptionLabel'];
146 $output .= $this->renderOptionTag($value, $label, false) . LF;
147 }
148 foreach ($options as $value => $label) {
149 $isSelected = $this->isSelected($value);
150 $output .= $this->renderOptionTag($value, $label, $isSelected) . LF;
151 }
152 return $output;
153 }
154
155 /**
156 * Render the option tags.
157 *
158 * @return array an associative array of options, key will be the value of the option tag
159 */
160 protected function getOptions()
161 {
162 if (!is_array($this->arguments['options']) && !$this->arguments['options'] instanceof \Traversable) {
163 return [];
164 }
165 $options = [];
166 $optionsArgument = $this->arguments['options'];
167 foreach ($optionsArgument as $key => $value) {
168 if (is_object($value) || is_array($value)) {
169 if ($this->hasArgument('optionValueField')) {
170 $key = \TYPO3\CMS\Extbase\Reflection\ObjectAccess::getPropertyPath($value, $this->arguments['optionValueField']);
171 if (is_object($key)) {
172 if (method_exists($key, '__toString')) {
173 $key = (string)$key;
174 } else {
175 throw new \TYPO3\CMS\Fluid\Core\ViewHelper\Exception('Identifying value for object of class "' . get_class($value) . '" was an object.', 1247827428);
176 }
177 }
178 // @todo use $this->persistenceManager->isNewObject() once it is implemented
179 } elseif ($this->persistenceManager->getIdentifierByObject($value) !== null) {
180 $key = $this->persistenceManager->getIdentifierByObject($value);
181 } elseif (method_exists($value, '__toString')) {
182 $key = (string)$value;
183 } else {
184 throw new \TYPO3\CMS\Fluid\Core\ViewHelper\Exception('No identifying value for object of class "' . get_class($value) . '" found.', 1247826696);
185 }
186 if ($this->hasArgument('optionLabelField')) {
187 $value = \TYPO3\CMS\Extbase\Reflection\ObjectAccess::getPropertyPath($value, $this->arguments['optionLabelField']);
188 if (is_object($value)) {
189 if (method_exists($value, '__toString')) {
190 $value = (string)$value;
191 } else {
192 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);
193 }
194 }
195 } elseif (method_exists($value, '__toString')) {
196 $value = (string)$value;
197 // @todo use $this->persistenceManager->isNewObject() once it is implemented
198 } elseif ($this->persistenceManager->getIdentifierByObject($value) !== null) {
199 $value = $this->persistenceManager->getIdentifierByObject($value);
200 }
201 }
202 $options[$key] = $value;
203 }
204 if ($this->arguments['sortByOptionLabel']) {
205 asort($options, SORT_LOCALE_STRING);
206 }
207 return $options;
208 }
209
210 /**
211 * Render the option tags.
212 *
213 * @param mixed $value Value to check for
214 * @return bool TRUE if the value should be marked a s selected; FALSE otherwise
215 */
216 protected function isSelected($value)
217 {
218 $selectedValue = $this->getSelectedValue();
219 if ($value === $selectedValue || (string)$value === $selectedValue) {
220 return true;
221 }
222 if ($this->hasArgument('multiple')) {
223 if (is_null($selectedValue) && $this->arguments['selectAllByDefault'] === true) {
224 return true;
225 } elseif (is_array($selectedValue) && in_array($value, $selectedValue)) {
226 return true;
227 }
228 }
229 return false;
230 }
231
232 /**
233 * Retrieves the selected value(s)
234 *
235 * @return mixed value string or an array of strings
236 */
237 protected function getSelectedValue()
238 {
239 $this->setRespectSubmittedDataValue(true);
240 $value = $this->getValueAttribute();
241 if (!is_array($value) && !$value instanceof \Traversable) {
242 return $this->getOptionValueScalar($value);
243 }
244 $selectedValues = [];
245 foreach ($value as $selectedValueElement) {
246 $selectedValues[] = $this->getOptionValueScalar($selectedValueElement);
247 }
248 return $selectedValues;
249 }
250
251 /**
252 * Get the option value for an object
253 *
254 * @param mixed $valueElement
255 * @return string
256 */
257 protected function getOptionValueScalar($valueElement)
258 {
259 if (is_object($valueElement)) {
260 if ($this->hasArgument('optionValueField')) {
261 return \TYPO3\CMS\Extbase\Reflection\ObjectAccess::getPropertyPath($valueElement, $this->arguments['optionValueField']);
262 } else {
263 // @todo use $this->persistenceManager->isNewObject() once it is implemented
264 if ($this->persistenceManager->getIdentifierByObject($valueElement) !== null) {
265 return $this->persistenceManager->getIdentifierByObject($valueElement);
266 } else {
267 return (string)$valueElement;
268 }
269 }
270 } else {
271 return $valueElement;
272 }
273 }
274
275 /**
276 * Render one option tag
277 *
278 * @param string $value value attribute of the option tag (will be escaped)
279 * @param string $label content of the option tag (will be escaped)
280 * @param bool $isSelected specifies wheter or not to add selected attribute
281 * @return string the rendered option tag
282 */
283 protected function renderOptionTag($value, $label, $isSelected)
284 {
285 $output = '<option value="' . htmlspecialchars($value) . '"';
286 if ($isSelected) {
287 $output .= ' selected="selected"';
288 }
289 $output .= '>' . htmlspecialchars($label) . '</option>';
290 return $output;
291 }
292 }