[BUGFIX] Fix several typos in php comments
[Packages/TYPO3.CMS.git] / typo3 / sysext / backend / Classes / Form / Element / AbstractFormElement.php
1 <?php
2 namespace TYPO3\CMS\Backend\Form\Element;
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 use TYPO3\CMS\Backend\Form\AbstractNode;
18 use TYPO3\CMS\Backend\Form\NodeFactory;
19 use TYPO3\CMS\Backend\Utility\BackendUtility;
20 use TYPO3\CMS\Core\Authentication\BackendUserAuthentication;
21 use TYPO3\CMS\Core\Imaging\IconFactory;
22 use TYPO3\CMS\Core\Localization\LanguageService;
23 use TYPO3\CMS\Core\Utility\ArrayUtility;
24 use TYPO3\CMS\Core\Utility\GeneralUtility;
25 use TYPO3\CMS\Core\Utility\MathUtility;
26
27 /**
28 * Base class for form elements of FormEngine. Contains several helper methods used by single elements.
29 */
30 abstract class AbstractFormElement extends AbstractNode
31 {
32 /**
33 * Default width value for a couple of elements like text
34 *
35 * @var int
36 */
37 protected $defaultInputWidth = 30;
38
39 /**
40 * Minimum width value for a couple of elements like text
41 *
42 * @var int
43 */
44 protected $minimumInputWidth = 10;
45
46 /**
47 * Maximum width value for a couple of elements like text
48 *
49 * @var int
50 */
51 protected $maxInputWidth = 50;
52
53 /**
54 * @var IconFactory
55 */
56 protected $iconFactory;
57
58 /**
59 * Container objects give $nodeFactory down to other containers.
60 *
61 * @param NodeFactory $nodeFactory
62 * @param array $data
63 */
64 public function __construct(NodeFactory $nodeFactory, array $data)
65 {
66 parent::__construct($nodeFactory, $data);
67 $this->iconFactory = GeneralUtility::makeInstance(IconFactory::class);
68 }
69
70 /**
71 * Merge field information configuration with default and render them.
72 *
73 * @return array Result array
74 */
75 protected function renderFieldInformation(): array
76 {
77 $options = $this->data;
78 $fieldInformation = $this->defaultFieldInformation;
79 $fieldInformationFromTca = $options['parameterArray']['fieldConf']['config']['fieldInformation'] ?? [];
80 ArrayUtility::mergeRecursiveWithOverrule($fieldInformation, $fieldInformationFromTca);
81 $options['renderType'] = 'fieldInformation';
82 $options['renderData']['fieldInformation'] = $fieldInformation;
83 return $this->nodeFactory->create($options)->render();
84 }
85
86 /**
87 * Merge field control configuration with default controls and render them.
88 *
89 * @return array Result array
90 */
91 protected function renderFieldControl(): array
92 {
93 $options = $this->data;
94 $fieldControl = $this->defaultFieldControl;
95 $fieldControlFromTca = $options['parameterArray']['fieldConf']['config']['fieldControl'] ?? [];
96 ArrayUtility::mergeRecursiveWithOverrule($fieldControl, $fieldControlFromTca);
97 $options['renderType'] = 'fieldControl';
98 $options['renderData']['fieldControl'] = $fieldControl;
99 return $this->nodeFactory->create($options)->render();
100 }
101
102 /**
103 * Merge field wizard configuration with default wizards and render them.
104 *
105 * @return array Result array
106 */
107 protected function renderFieldWizard(): array
108 {
109 $options = $this->data;
110 $fieldWizard = $this->defaultFieldWizard;
111 $fieldWizardFromTca = $options['parameterArray']['fieldConf']['config']['fieldWizard'] ?? [];
112 ArrayUtility::mergeRecursiveWithOverrule($fieldWizard, $fieldWizardFromTca);
113 $options['renderType'] = 'fieldWizard';
114 $options['renderData']['fieldWizard'] = $fieldWizard;
115 return $this->nodeFactory->create($options)->render();
116 }
117
118 /**
119 * Returns true if the "null value" checkbox should be rendered. This is used in some
120 * "text" based types like "text" and "input" for some renderType's.
121 *
122 * A field has eval=null set, but has no useOverridePlaceholder defined.
123 * Goal is to have a field that can distinct between NULL and empty string in the database.
124 * A checkbox and an additional hidden field will be created, both with the same name
125 * and prefixed with "control[active]". If the checkbox is set (value 1), the value from the casual
126 * input field will be written to the database. If the checkbox is not set, the hidden field
127 * transfers value=0 to DataHandler, the value of the input field will then be reset to NULL by the
128 * DataHandler at an early point in processing, so NULL will be written to DB as field value.
129 *
130 * All that only works if the field is not within flex form scope since flex forms
131 * can not store a "null" value or distinct it from "empty string".
132 *
133 * @return bool
134 */
135 protected function hasNullCheckboxButNoPlaceholder(): bool
136 {
137 $hasNullCheckboxNoPlaceholder = false;
138 $parameterArray = $this->data['parameterArray'];
139 $mode = $parameterArray['fieldConf']['config']['mode'] ?? '';
140 if (empty($this->data['flexFormDataStructureIdentifier'])
141 && !empty($parameterArray['fieldConf']['config']['eval'])
142 && GeneralUtility::inList($parameterArray['fieldConf']['config']['eval'], 'null')
143 && ($mode !== 'useOrOverridePlaceholder')
144 ) {
145 $hasNullCheckboxNoPlaceholder = true;
146 }
147 return $hasNullCheckboxNoPlaceholder;
148 }
149
150 /**
151 * Returns true if the "null value" checkbox should be rendered and the placeholder
152 * handling is enabled. This is used in some "text" based types like "text" and
153 * "input" for some renderType's.
154 *
155 * A field has useOverridePlaceholder set and null in eval and is not within a flex form.
156 * Here, a value from a deeper DB structure can be "fetched up" as value, and can also be overridden by a
157 * local value. This is used in FAL, where eg. the "title" field can have the default value from sys_file_metadata,
158 * the title field of sys_file_reference is then set to NULL. Or the "override" checkbox is set, and a string
159 * or an empty string is then written to the field of sys_file_reference.
160 * The situation is similar to hasNullCheckboxButNoPlaceholder(), but additionally a "default" value should be shown.
161 * To achieve this, again a hidden control[hidden] field is added together with a checkbox with the same name
162 * to transfer the information whether the default value should be used or not: Checkbox checked transfers 1 as
163 * value in control[active], meaning the overridden value should be used.
164 * Additionally to the casual input field, a second field is added containing the "placeholder" value. This
165 * field has no name attribute and is not transferred at all. Those two are then hidden / shown depending
166 * on the state of the above checkbox in via JS.
167 *
168 * @return bool
169 */
170 protected function hasNullCheckboxWithPlaceholder(): bool
171 {
172 $hasNullCheckboxWithPlaceholder = false;
173 $parameterArray = $this->data['parameterArray'];
174 $mode = $parameterArray['fieldConf']['config']['mode'] ?? '';
175 if (empty($this->data['flexFormDataStructureIdentifier'])
176 && !empty($parameterArray['fieldConf']['config']['eval'])
177 && GeneralUtility::inList($parameterArray['fieldConf']['config']['eval'], 'null')
178 && ($mode === 'useOrOverridePlaceholder')
179 ) {
180 $hasNullCheckboxWithPlaceholder = true;
181 }
182 return $hasNullCheckboxWithPlaceholder;
183 }
184
185 /**
186 * Format field content if 'format' is set to date, filesize, ..., user
187 *
188 * @param string $format Configuration for the display.
189 * @param string $itemValue The value to display
190 * @param array $formatOptions Format options
191 * @return string Formatted field value
192 */
193 protected function formatValue($format, $itemValue, $formatOptions = [])
194 {
195 switch ($format) {
196 case 'date':
197 if ($itemValue) {
198 $option = isset($formatOptions['option']) ? trim($formatOptions['option']) : '';
199 if ($option) {
200 if (isset($formatOptions['strftime']) && $formatOptions['strftime']) {
201 $value = strftime($option, $itemValue);
202 } else {
203 $value = date($option, $itemValue);
204 }
205 } else {
206 $value = date('d-m-Y', $itemValue);
207 }
208 } else {
209 $value = '';
210 }
211 if (isset($formatOptions['appendAge']) && $formatOptions['appendAge']) {
212 $age = BackendUtility::calcAge(
213 $GLOBALS['EXEC_TIME'] - $itemValue,
214 $this->getLanguageService()->sL('LLL:EXT:core/Resources/Private/Language/locallang_core.xlf:labels.minutesHoursDaysYears')
215 );
216 $value .= ' (' . $age . ')';
217 }
218 $itemValue = $value;
219 break;
220 case 'datetime':
221 // compatibility with "eval" (type "input")
222 if ($itemValue !== '' && $itemValue !== null) {
223 $itemValue = BackendUtility::datetime((int)$itemValue);
224 }
225 break;
226 case 'time':
227 // compatibility with "eval" (type "input")
228 if ($itemValue !== '' && $itemValue !== null) {
229 $itemValue = BackendUtility::time((int)$itemValue, false);
230 }
231 break;
232 case 'timesec':
233 // compatibility with "eval" (type "input")
234 if ($itemValue !== '' && $itemValue !== null) {
235 $itemValue = BackendUtility::time((int)$itemValue);
236 }
237 break;
238 case 'year':
239 // compatibility with "eval" (type "input")
240 if ($itemValue !== '' && $itemValue !== null) {
241 $itemValue = date('Y', (int)$itemValue);
242 }
243 break;
244 case 'int':
245 $baseArr = ['dec' => 'd', 'hex' => 'x', 'HEX' => 'X', 'oct' => 'o', 'bin' => 'b'];
246 $base = isset($formatOptions['base']) ? trim($formatOptions['base']) : '';
247 $format = $baseArr[$base] ?? 'd';
248 $itemValue = sprintf('%' . $format, $itemValue);
249 break;
250 case 'float':
251 // default precision
252 $precision = 2;
253 if (isset($formatOptions['precision'])) {
254 $precision = MathUtility::forceIntegerInRange($formatOptions['precision'], 1, 10, $precision);
255 }
256 $itemValue = sprintf('%.' . $precision . 'f', $itemValue);
257 break;
258 case 'number':
259 $format = isset($formatOptions['option']) ? trim($formatOptions['option']) : '';
260 $itemValue = sprintf('%' . $format, $itemValue);
261 break;
262 case 'md5':
263 $itemValue = md5($itemValue);
264 break;
265 case 'filesize':
266 // We need to cast to int here, otherwise empty values result in empty output,
267 // but we expect zero.
268 $value = GeneralUtility::formatSize((int)$itemValue);
269 if (!empty($formatOptions['appendByteSize'])) {
270 $value .= ' (' . $itemValue . ')';
271 }
272 $itemValue = $value;
273 break;
274 case 'user':
275 $func = trim($formatOptions['userFunc']);
276 if ($func) {
277 $params = [
278 'value' => $itemValue,
279 'args' => $formatOptions['userFunc'],
280 'config' => [
281 'type' => 'none',
282 'format' => $format,
283 'format.' => $formatOptions,
284 ],
285 ];
286 $itemValue = GeneralUtility::callUserFunction($func, $params, $this);
287 }
288 break;
289 default:
290 // Do nothing e.g. when $format === ''
291 }
292 return $itemValue;
293 }
294
295 /**
296 * Returns the max width in pixels for an elements like input and text
297 *
298 * @param int $size The abstract size value (1-48)
299 * @return int Maximum width in pixels
300 */
301 protected function formMaxWidth($size = 48)
302 {
303 $compensationForLargeDocuments = 1.33;
304 $compensationForFormFields = 12;
305
306 $size = round($size * $compensationForLargeDocuments);
307 return ceil($size * $compensationForFormFields);
308 }
309
310 /***********************************************
311 * CheckboxElement related methods
312 ***********************************************/
313
314 /**
315 * Creates checkbox parameters
316 *
317 * @param string $itemName Form element name
318 * @param int $formElementValue The value of the checkbox (representing checkboxes with the bits)
319 * @param int $checkbox Checkbox # (0-9?)
320 * @param int $checkboxesCount Total number of checkboxes in the array.
321 * @param string $additionalJavaScript Additional JavaScript for the onclick handler.
322 * @return string The onclick attribute + possibly the checked-option set.
323 * @internal
324 */
325 protected function checkBoxParams($itemName, $formElementValue, $checkbox, $checkboxesCount, $additionalJavaScript = ''): string
326 {
327 $elementName = 'document.editform[' . GeneralUtility::quoteJSvalue($itemName) . ']';
328 $checkboxPow = 2 ** $checkbox;
329 $onClick = $elementName . '.value=this.checked?(' . $elementName . '.value|' . $checkboxPow . '):('
330 . $elementName . '.value&' . ((2 ** $checkboxesCount) - 1 - $checkboxPow) . ');' . $additionalJavaScript;
331 return ' onclick="' . htmlspecialchars($onClick) . '"' . ($formElementValue & $checkboxPow ? ' checked="checked"' : '');
332 }
333
334 /**
335 * Calculates the bootstrap grid classes based on the amount of columns
336 * defined in the checkbox item TCA
337 *
338 * @param $cols
339 * @return array
340 * @internal
341 */
342 protected function calculateColumnMarkup(int $cols): array
343 {
344 $colWidth = (int)floor(12 / $cols);
345 $colClass = 'col-md-12';
346 $colClear = [];
347 if ($colWidth === 6) {
348 $colClass = 'col-sm-6';
349 $colClear = [
350 2 => 'visible-sm-block visible-md-block visible-lg-block',
351 ];
352 } elseif ($colWidth === 4) {
353 $colClass = 'col-sm-4';
354 $colClear = [
355 3 => 'visible-sm-block visible-md-block visible-lg-block',
356 ];
357 } elseif ($colWidth === 3) {
358 $colClass = 'col-sm-6 col-md-3';
359 $colClear = [
360 2 => 'visible-sm-block',
361 4 => 'visible-md-block visible-lg-block',
362 ];
363 } elseif ($colWidth <= 2) {
364 $colClass = 'checkbox-column col-sm-6 col-md-3 col-lg-2';
365 $colClear = [
366 2 => 'visible-sm-block',
367 4 => 'visible-md-block',
368 6 => 'visible-lg-block'
369 ];
370 }
371 return [$colClass, $colClear];
372 }
373
374 /**
375 * Append the value of a form field to its label
376 *
377 * @param string|int $label The label which can also be an integer
378 * @param string|int $value The value which can also be an integer
379 * @return string|int
380 */
381 protected function appendValueToLabelInDebugMode($label, $value)
382 {
383 if ($value !== '' && $GLOBALS['TYPO3_CONF_VARS']['BE']['debug'] && $this->getBackendUser()->isAdmin()) {
384 return $label . ' [' . $value . ']';
385 }
386
387 return $label;
388 }
389
390 /**
391 * @return LanguageService
392 */
393 protected function getLanguageService()
394 {
395 return $GLOBALS['LANG'];
396 }
397
398 /**
399 * Returns the current BE user.
400 *
401 * @return BackendUserAuthentication
402 */
403 protected function getBackendUser()
404 {
405 return $GLOBALS['BE_USER'];
406 }
407 }