[FEATURE] EXT:form - integrate new form framework
[Packages/TYPO3.CMS.git] / typo3 / sysext / form / Classes / Domain / Model / FormElements / FormElementInterface.php
1 <?php
2 declare(strict_types=1);
3 namespace TYPO3\CMS\Form\Domain\Model\FormElements;
4
5 /*
6 * This file is part of the TYPO3 CMS project.
7 *
8 * It is free software; you can redistribute it and/or modify it under
9 * the terms of the GNU General Public License, either version 2
10 * of the License, or any later version.
11 *
12 * For the full copyright and license information, please read the
13 * LICENSE.txt file that was distributed with this source code.
14 *
15 * The TYPO3 project - inspiring people to share!
16 */
17
18 use TYPO3\CMS\Extbase\Validation\Validator\ValidatorInterface;
19 use TYPO3\CMS\Form\Domain\Model\Renderable\RenderableInterface;
20 use TYPO3\CMS\Form\Domain\Runtime\FormRuntime;
21
22 /**
23 * A base form element interface, which can be the starting point for creating
24 * custom (PHP-based) Form Elements.
25 *
26 * A *FormElement* is a part of a *Page*, which in turn is part of a FormDefinition.
27 * See {@link FormDefinition} for an in-depth explanation.
28 *
29 * **Often, you should rather subclass {@link AbstractFormElement} instead of
30 * implementing this interface.**
31 *
32 * Scope: frontend
33 */
34 interface FormElementInterface extends RenderableInterface
35 {
36
37 /**
38 * Will be called as soon as the element is (tried to be) added to a form
39 * @see registerInFormIfPossible()
40 *
41 * @return void
42 * @internal
43 */
44 public function initializeFormElement();
45
46 /**
47 * Returns a unique identifier of this element.
48 * While element identifiers are only unique within one form,
49 * this includes the identifier of the form itself, making it "globally" unique
50 *
51 * @return string the "globally" unique identifier of this element
52 * @api
53 */
54 public function getUniqueIdentifier(): string;
55
56 /**
57 * Get the default value with which the Form Element should be initialized
58 * during display.
59 *
60 * @return mixed the default value for this Form Element
61 * @api
62 */
63 public function getDefaultValue();
64
65 /**
66 * Set the default value with which the Form Element should be initialized
67 * during display.
68 *
69 * @param mixed $defaultValue the default value for this Form Element
70 * @api
71 */
72 public function setDefaultValue($defaultValue);
73
74 /**
75 * Set an element-specific configuration property.
76 *
77 * @param string $key
78 * @param mixed $value
79 * @return void
80 * @api
81 */
82 public function setProperty(string $key, $value);
83
84 /**
85 * Get all element-specific configuration properties
86 *
87 * @return array
88 * @api
89 */
90 public function getProperties(): array;
91
92 /**
93 * Set a rendering option
94 *
95 * @param string $key
96 * @param mixed $value
97 * @api
98 */
99 public function setRenderingOption(string $key, $value);
100
101 /**
102 * Returns the child validators of the ConjunctionValidator that is registered for this element
103 *
104 * @return \SplObjectStorage<ValidatorInterface>
105 * @internal
106 */
107 public function getValidators(): \SplObjectStorage;
108
109 /**
110 * Registers a validator for this element
111 *
112 * @param ValidatorInterface $validator
113 * @return void
114 * @api
115 */
116 public function addValidator(ValidatorInterface $validator);
117
118 /**
119 * Set the target data type for this element
120 *
121 * @param string $dataType the target data type
122 * @return void
123 * @api
124 */
125 public function setDataType(string $dataType);
126
127 /**
128 * Whether or not this element is required
129 *
130 * @return bool
131 * @api
132 */
133 public function isRequired(): bool;
134
135 /**
136 * This callback is invoked by the FormRuntime whenever values are mapped and validated
137 * (after a form page was submitted)
138 *
139 * @param FormRuntime $formRuntime
140 * @param mixed $elementValue submitted value of the element *before post processing*
141 * @param array $requestArguments submitted raw request values
142 * @return void
143 * @see FormRuntime::mapAndValidate()
144 * @api
145 */
146 public function onSubmit(FormRuntime $formRuntime, &$elementValue, array $requestArguments = []);
147 }