14d02c6f15a05d06a6f9c684c10df8eb431b825b
[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 * = Custom options and option group rendering =
40 *
41 * Child nodes can be used to create a completely custom set of ``<option>`` and ``<optgroup>`` tags in a way compatible with
42 * the HMAC generation. To do so, leave out the ``options`` argument and use child ViewHelpers:
43 * <code title="Custom options and optgroup">
44 * <f:form.select name="myproperty">
45 * <f:form.select.option value="1">Option one</f:form.select.option>
46 * <f:form.select.option value="2">Option two</f:form.select.option>
47 * <f:form.select.optgroup>
48 * <f:form.select.option value="3">Grouped option one</f:form.select.option>
49 * <f:form.select.option value="4">Grouped option twi</f:form.select.option>
50 * </f:form.select.optgroup>
51 * </f:form.select>
52 * </code>
53 * Note: do not use vanilla ``<option>`` or ``<optgroup>`` tags! They will invalidate the HMAC generation!
54 *
55 * = Usage on domain objects =
56 *
57 * If you want to output domain objects, you can just pass them as array into the "options" parameter.
58 * To define what domain object value should be used as option key, use the "optionValueField" variable. Same goes for optionLabelField.
59 * If neither is given, the Identifier (UID/uid) and the __toString() method are tried as fallbacks.
60 *
61 * If the optionValueField variable is set, the getter named after that value is used to retrieve the option key.
62 * If the optionLabelField variable is set, the getter named after that value is used to retrieve the option value.
63 *
64 * If the prependOptionLabel variable is set, an option item is added in first position, bearing an empty string or -
65 * If provided, the value of the prependOptionValue variable as value.
66 *
67 * <code title="Domain objects">
68 * <f:form.select name="users" options="{userArray}" optionValueField="id" optionLabelField="firstName" />
69 * </code>
70 * In the above example, the userArray is an array of "User" domain objects, with no array key specified.
71 *
72 * 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.
73 *
74 * The "value" property now expects a domain object, and tests for object equivalence.
75 *
76 * @api
77 */
78 class SelectViewHelper extends \TYPO3\CMS\Fluid\ViewHelpers\Form\AbstractFormFieldViewHelper
79 {
80 /**
81 * @var string
82 */
83 protected $tagName = 'select';
84
85 /**
86 * @var mixed
87 */
88 protected $selectedValue;
89
90 /**
91 * Initialize arguments.
92 *
93 * @api
94 */
95 public function initializeArguments()
96 {
97 parent::initializeArguments();
98 $this->registerUniversalTagAttributes();
99 $this->registerTagAttribute('size', 'string', 'Size of input field');
100 $this->registerTagAttribute('disabled', 'string', 'Specifies that the input element should be disabled when the page loads');
101 $this->registerArgument('options', 'array', 'Associative array with internal IDs as key, and the values are displayed in the select box. Can be combined with or replaced by child f:form.select.* nodes.');
102 $this->registerArgument('optionsAfterContent', 'boolean', 'If true, places auto-generated option tags after those rendered in the tag content. If false, automatic options come first.', false, false);
103 $this->registerArgument('optionValueField', 'string', 'If specified, will call the appropriate getter on each object to determine the value.');
104 $this->registerArgument('optionLabelField', 'string', 'If specified, will call the appropriate getter on each object to determine the label.');
105 $this->registerArgument('sortByOptionLabel', 'boolean', 'If true, List will be sorted by label.', false, false);
106 $this->registerArgument('selectAllByDefault', 'boolean', 'If specified options are selected if none was set before.', false, false);
107 $this->registerArgument('errorClass', 'string', 'CSS class to set if there are errors for this view helper', false, 'f3-form-error');
108 $this->registerArgument('prependOptionLabel', 'string', 'If specified, will provide an option at first position with the specified label.');
109 $this->registerArgument('prependOptionValue', 'string', 'If specified, will provide an option at first position with the specified value.');
110 $this->registerArgument('multiple', 'boolean', 'If set multiple options may be selected.', false, false);
111 $this->registerArgument('required', 'boolean', 'If set no empty value is allowed.', false, false);
112 }
113
114 /**
115 * Render the tag.
116 *
117 * @return string rendered tag.
118 * @api
119 */
120 public function render()
121 {
122 if (isset($this->arguments['required']) && $this->arguments['required']) {
123 $this->tag->addAttribute('required', 'required');
124 }
125 $name = $this->getName();
126 if (isset($this->arguments['multiple']) && $this->arguments['multiple']) {
127 $this->tag->addAttribute('multiple', 'multiple');
128 $name .= '[]';
129 }
130 $this->tag->addAttribute('name', $name);
131 $options = $this->getOptions();
132
133 $this->addAdditionalIdentityPropertiesIfNeeded();
134 $this->setErrorClassAttribute();
135 $content = '';
136 // register field name for token generation.
137 // in case it is a multi-select, we need to register the field name
138 // as often as there are elements in the box
139 if (isset($this->arguments['multiple']) && $this->arguments['multiple']) {
140 $content .= $this->renderHiddenFieldForEmptyValue();
141 $optionsCount = count($options);
142 for ($i = 0; $i < $optionsCount; $i++) {
143 $this->registerFieldNameForFormTokenGeneration($name);
144 }
145 // save the parent field name so that any child f:form.select.option
146 // tag will know to call registerFieldNameForFormTokenGeneration
147 $this->viewHelperVariableContainer->addOrUpdate(
148 static::class,
149 'registerFieldNameForFormTokenGeneration',
150 $name
151 );
152 } else {
153 $this->registerFieldNameForFormTokenGeneration($name);
154 }
155
156 $this->viewHelperVariableContainer->addOrUpdate(static::class, 'selectedValue', $this->getSelectedValue());
157 $prependContent = $this->renderPrependOptionTag();
158 $tagContent = $this->renderOptionTags($options);
159 $childContent = $this->renderChildren();
160 $this->viewHelperVariableContainer->remove(static::class, 'selectedValue');
161 $this->viewHelperVariableContainer->remove(static::class, 'registerFieldNameForFormTokenGeneration');
162 if (isset($this->arguments['optionsAfterContent']) && $this->arguments['optionsAfterContent']) {
163 $tagContent = $childContent . $tagContent;
164 } else {
165 $tagContent .= $childContent;
166 }
167 $tagContent = $prependContent . $tagContent;
168
169 $this->tag->forceClosingTag(true);
170 $this->tag->setContent($tagContent);
171 $content .= $this->tag->render();
172 return $content;
173 }
174
175 /**
176 * Render prepended option tag
177 *
178 * @return string rendered prepended empty option
179 */
180 protected function renderPrependOptionTag()
181 {
182 $output = '';
183 if ($this->hasArgument('prependOptionLabel')) {
184 $value = $this->hasArgument('prependOptionValue') ? $this->arguments['prependOptionValue'] : '';
185 $label = $this->arguments['prependOptionLabel'];
186 $output .= $this->renderOptionTag($value, $label, false) . LF;
187 }
188 return $output;
189 }
190
191 /**
192 * Render the option tags.
193 *
194 * @param array $options the options for the form.
195 * @return string rendered tags.
196 */
197 protected function renderOptionTags($options)
198 {
199 $output = '';
200 foreach ($options as $value => $label) {
201 $isSelected = $this->isSelected($value);
202 $output .= $this->renderOptionTag($value, $label, $isSelected) . LF;
203 }
204 return $output;
205 }
206
207 /**
208 * Render the option tags.
209 *
210 * @return array an associative array of options, key will be the value of the option tag
211 */
212 protected function getOptions()
213 {
214 if (!is_array($this->arguments['options']) && !$this->arguments['options'] instanceof \Traversable) {
215 return [];
216 }
217 $options = [];
218 $optionsArgument = $this->arguments['options'];
219 foreach ($optionsArgument as $key => $value) {
220 if (is_object($value) || is_array($value)) {
221 if ($this->hasArgument('optionValueField')) {
222 $key = \TYPO3\CMS\Extbase\Reflection\ObjectAccess::getPropertyPath($value, $this->arguments['optionValueField']);
223 if (is_object($key)) {
224 if (method_exists($key, '__toString')) {
225 $key = (string)$key;
226 } else {
227 throw new \TYPO3\CMS\Fluid\Core\ViewHelper\Exception('Identifying value for object of class "' . get_class($value) . '" was an object.', 1247827428);
228 }
229 }
230 } elseif ($this->persistenceManager->getIdentifierByObject($value) !== null) {
231 // @todo use $this->persistenceManager->isNewObject() once it is implemented
232 $key = $this->persistenceManager->getIdentifierByObject($value);
233 } elseif (method_exists($value, '__toString')) {
234 $key = (string)$value;
235 } else {
236 throw new \TYPO3\CMS\Fluid\Core\ViewHelper\Exception('No identifying value for object of class "' . get_class($value) . '" found.', 1247826696);
237 }
238 if ($this->hasArgument('optionLabelField')) {
239 $value = \TYPO3\CMS\Extbase\Reflection\ObjectAccess::getPropertyPath($value, $this->arguments['optionLabelField']);
240 if (is_object($value)) {
241 if (method_exists($value, '__toString')) {
242 $value = (string)$value;
243 } else {
244 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);
245 }
246 }
247 } elseif (method_exists($value, '__toString')) {
248 $value = (string)$value;
249 } elseif ($this->persistenceManager->getIdentifierByObject($value) !== null) {
250 // @todo use $this->persistenceManager->isNewObject() once it is implemented
251 $value = $this->persistenceManager->getIdentifierByObject($value);
252 }
253 }
254 $options[$key] = $value;
255 }
256 if ($this->arguments['sortByOptionLabel']) {
257 asort($options, SORT_LOCALE_STRING);
258 }
259 return $options;
260 }
261
262 /**
263 * Render the option tags.
264 *
265 * @param mixed $value Value to check for
266 * @return bool TRUE if the value should be marked a s selected; FALSE otherwise
267 */
268 protected function isSelected($value)
269 {
270 $selectedValue = $this->getSelectedValue();
271 if ($value === $selectedValue || (string)$value === $selectedValue) {
272 return true;
273 }
274 if ($this->hasArgument('multiple')) {
275 if ($selectedValue === null && $this->arguments['selectAllByDefault'] === true) {
276 return true;
277 }
278 if (is_array($selectedValue) && in_array($value, $selectedValue)) {
279 return true;
280 }
281 }
282 return false;
283 }
284
285 /**
286 * Retrieves the selected value(s)
287 *
288 * @return mixed value string or an array of strings
289 */
290 protected function getSelectedValue()
291 {
292 $this->setRespectSubmittedDataValue(true);
293 $value = $this->getValueAttribute();
294 if (!is_array($value) && !$value instanceof \Traversable) {
295 return $this->getOptionValueScalar($value);
296 }
297 $selectedValues = [];
298 foreach ($value as $selectedValueElement) {
299 $selectedValues[] = $this->getOptionValueScalar($selectedValueElement);
300 }
301 return $selectedValues;
302 }
303
304 /**
305 * Get the option value for an object
306 *
307 * @param mixed $valueElement
308 * @return string
309 */
310 protected function getOptionValueScalar($valueElement)
311 {
312 if (is_object($valueElement)) {
313 if ($this->hasArgument('optionValueField')) {
314 return \TYPO3\CMS\Extbase\Reflection\ObjectAccess::getPropertyPath($valueElement, $this->arguments['optionValueField']);
315 }
316 // @todo use $this->persistenceManager->isNewObject() once it is implemented
317 if ($this->persistenceManager->getIdentifierByObject($valueElement) !== null) {
318 return $this->persistenceManager->getIdentifierByObject($valueElement);
319 }
320 return (string)$valueElement;
321 }
322 return $valueElement;
323 }
324
325 /**
326 * Render one option tag
327 *
328 * @param string $value value attribute of the option tag (will be escaped)
329 * @param string $label content of the option tag (will be escaped)
330 * @param bool $isSelected specifies wheter or not to add selected attribute
331 * @return string the rendered option tag
332 */
333 protected function renderOptionTag($value, $label, $isSelected)
334 {
335 $output = '<option value="' . htmlspecialchars($value) . '"';
336 if ($isSelected) {
337 $output .= ' selected="selected"';
338 }
339 $output .= '>' . htmlspecialchars($label) . '</option>';
340 return $output;
341 }
342 }