[TASK] Update TypoScript include
[Packages/TYPO3.CMS.git] / typo3 / sysext / form / Documentation / Concepts / Configuration / Index.rst
1 .. include:: ../../Includes.txt
2
3
4 .. _concepts-configuration:
5
6 Configuration
7 =============
8
9
10 .. _concepts-configuration-whysomuchconfiguration:
11
12 A lot of configuration. Why?
13 ----------------------------
14
15 The requirements for building forms in a declarative and programmatic way
16 are complex. What we have learned so far is that the program code must be
17 kept as generic as possible to handle the dynamics of forms, but a generic
18 program code means a lot of configurative overhead.
19
20 Initially, the configuration may overwhelm you, but it also has some great
21 advantages. Many aspects of EXT:form can be manipulated in a purely
22 configurative manner without involving a developer.
23
24 Furthermore, we wanted to avoid the configuration being done at places
25 whose context actually suggests something different. This pedantry,
26 however, leads to the situation in which certain settings have to be
27 defined multiple times at multiple places. This may seem nonsensical, but
28 it avoids unpredictable behaviour. Within the form framework, nothing
29 happens magically. It is all about configuration.
30
31
32 .. _concepts-configuration-whyyaml:
33
34 Why YAML?
35 ---------
36
37 Former versions of EXT:form used a subset of TypoScript to describe the
38 definition of a specific form and the behaviour of the included form
39 elements. This led to a lot of confusion from integrators because the
40 implemented definition language looked like TypoScript but did not behave
41 like TypoScript.
42
43 Since the definition of forms and form elements must be declarative, the
44 EXT:form team decided to use YAML. Just through the visual appearance of
45 YAML, it should be clear to everyone that neither magic nor TypoScript
46 stdWrap functionality are possible.
47
48
49 .. _concepts-configuration-yamlregistration:
50
51 YAML registration
52 -----------------
53
54 At the moment, configuration via YAML is not natively integrated into the
55 core of TYPO3. You have to make a short detour by using TypoScript in order
56 to register your YAML configuration. Furthermore, there is a "speciality"
57 regarding the integration of your YAML configuration for the backend
58 module.
59
60 .. hint::
61
62 We recommend using a `site package <https://de.slideshare.net/benjaminkott/typo3-the-anatomy-of-sitepackages>`_.
63 This will make your life easier if you want to customise EXT:form
64 heavily in order to suit the customer's needs.
65
66
67 .. _concepts-configuration-yamlregistration-frontend:
68
69 YAML registration for the frontend
70 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
71
72 EXT:form registers two YAML configuration files which are required for the
73 frontend.
74
75 .. code-block:: typoscript
76
77 plugin.tx_form {
78 settings {
79 yamlConfigurations {
80 10 = EXT:form/Configuration/Yaml/BaseSetup.yaml
81 20 = EXT:form/Configuration/Yaml/FormEngineSetup.yaml
82 }
83 }
84 }
85
86 Since the keys 10 and 20 are already taken, we recommend registering your
87 own configuration beginning with the key ``100``.
88
89 .. code-block:: typoscript
90
91 plugin.tx_form {
92 settings {
93 yamlConfigurations {
94 100 = EXT:my_site_package/Configuration/Yaml/CustomFormSetup.yaml
95 }
96 }
97 }
98
99 .. _concepts-configuration-yamlregistration-backend:
100
101 YAML registration for the backend
102 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
103
104 EXT:form registers three YAML configuration files which are required for
105 the backend.
106
107 .. code-block:: typoscript
108
109 module.tx_form {
110 settings {
111 yamlConfigurations {
112 10 = EXT:form/Configuration/Yaml/BaseSetup.yaml
113 20 = EXT:form/Configuration/Yaml/FormEditorSetup.yaml
114 30 = EXT:form/Configuration/Yaml/FormEngineSetup.yaml
115 }
116 }
117 }
118
119 Since the keys 10, 20, and 30 are already taken, we recommend registering
120 your own configuration beginning with the key ``100``.
121
122 .. code-block:: typoscript
123
124 module.tx_form {
125 settings {
126 yamlConfigurations {
127 100 = EXT:my_site_package/Configuration/Yaml/CustomFormSetup.yaml
128 }
129 }
130 }
131
132 .. important::
133 Consider the following methods to register TypoScript for the backend.
134
135 The backend module of EXT:form is based on Extbase. Such backend modules
136 can, like frontend plugins, be configured via TypoScript. The frontend
137 plugins are configured below ``plugin.tx_[pluginkey]``. For the
138 configuration of the backend ``module.tx_[pluginkey]`` is used.
139
140 There are different ways to include the TypoScript configuration for the
141 backend:
142
143 - a) use the API function ``\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addTypoScriptSetup()``,
144 - b) add the configuration to your existing TypoScript template.
145
146 In both cases, the ``form editor`` will work as expected regardless the
147 chosen page from the page tree. If using the aforementioned method b, the
148 configuration would only be valid on a specific page tree, unless you add
149 your configuration to all trees within your installation. Nevertheless,
150 being on the root page (uid 0) would still be a problem.
151
152 To sum it up: choose either method a or b, and you will be fine.
153
154 .. _concepts-configuration-yamlregistration-backend-addtyposcriptsetup:
155
156 YAML registration for the backend via addTypoScriptSetup()
157 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
158
159 Add the following PHP code to your :file:`ext_localconf.php` of your site
160 package::
161
162 defined('TYPO3_MODE') or die();
163
164 call_user_func(function () {
165 if (TYPO3_MODE === 'BE') {
166 \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addTypoScriptSetup(
167 trim('
168 module.tx_form {
169 settings {
170 yamlConfigurations {
171 100 = EXT:my_site_package/Configuration/Yaml/CustomFormSetup.yaml
172 }
173 }
174 }
175 ')
176 );
177 }
178 });
179
180
181 .. _concepts-configuration-configurationaspects:
182
183 Configuration aspects
184 ---------------------
185
186 In EXT:form, four aspects can be configured:
187
188 - the behaviour of the frontend rendering,
189 - the behaviour of the ``form editor``,
190 - the behaviour of the ``form manager``, and
191 - the behaviour of the ``form plugin``.
192
193 Those aspects are defined in separate files which are only loaded in the
194 frontend/ backend when needed. This approach has two advantages:
195
196 - increased clarity,
197 - increased performance, e.g. the ``form editor`` configuration is not
198 needed in the frontend and therefore not loaded.
199
200 It is up to you if you want to follow this guideline or if you want to put
201 the whole configuration into one large file.
202
203 There are some configurational aspects which cannot explicitly be assigned
204 to either the frontend or the backend. Instead, the configuration is
205 valid for both areas. For example, within the backend, the whole frontend
206 configuration is required in order to allow the form preview to work
207 properly. In addition, as soon as the form is rendered via the ``form
208 plugin``, the ``FormEngine`` configuration is needed to interpret the
209 overridden finisher configuration correctly.
210
211
212 .. _concepts-configuration-inheritances:
213
214 Inheritances
215 ------------
216
217 The final YAML configuration is not based on one huge file. Instead, it is
218 a compilation of a sequential process:
219
220 - First of all, all registered configuration files are parsed as YAML and
221 are overlaid according to their order.
222 - After that, the ``__inheritances`` operator is applied. It is a unique
223 operator introduced by the form framework.
224 - Finally, all configuration entries with a value of ``null`` are deleted.
225
226 Additionally, the frontend configuration can be extended/ overridden by
227 TypoScript:
228
229 .. code-block:: typoscript
230
231 plugin.tx_form {
232 settings {
233 yamlSettingsOverrides {
234 ...
235 }
236 }
237 }
238
239 .. note::
240
241 Your TypoScript overrides are not interpreted by the ``form editor``,
242 i.e. those settings are ignored.
243
244 .. note::
245
246 The described process is quite handy for you. As soon as you are working
247 with your :ref:`own configuration files <concepts-configuration-yamlregistration>`,
248 you only have to define the differences compared to the previously
249 loaded configuration files.
250
251 For example, if you want to override the fluid templates and you therefore
252 register an additional configuration file via
253
254 .. code-block:: typoscript
255
256 plugin.tx_form {
257 settings {
258 yamlConfigurations {
259 # register your own additional configuration
260 # choose a number higher than 30 (below is reserved)
261 100 = EXT:my_site_package/Configuration/Yaml/CustomFormSetup.yaml
262 }
263 }
264 }
265
266 ... you only have to define the following YAML setup in ``EXT:my_site_package/Configuration/Yaml/CustomFormSetup.yaml``:
267
268 .. code-block:: yaml
269
270 TYPO3:
271 CMS:
272 Form:
273 prototypes:
274 standard:
275 formElementsDefinition:
276 Form:
277 renderingOptions:
278 templateRootPaths:
279 20: 'EXT:my_site_package/Resources/Private/Frontend/Templates/'
280 partialRootPaths:
281 20: 'EXT:my_site_package/Resources/Private/Frontend/Partials/'
282 layoutRootPaths:
283 20: 'EXT:my_site_package/Resources/Private/Frontend/Layouts/'
284
285 The values of your own configuration file will overrule the corresponding
286 values of the basic configuration file (:file:`EXT:form/Configuration/Yaml/BaseSetup.yaml`).
287
288
289 .. _concepts-configuration-inheritances-operator:
290
291 __inheritances operator
292 ^^^^^^^^^^^^^^^^^^^^^^^
293
294 The ``__inheritances`` operator is an extremely useful instrument. Using it
295 helps to significantly reduce the configuration effort. It behaves similar
296 to the ``<`` operator in TypoScript. That is, the definition of the source
297 object is copied to the target object. The configuration can be inherited
298 from several parent objects and can be overridden afterwards. Two simple
299 examples will show you the usage and behaviour of the ``__inheritances``
300 operator.
301
302 .. code-block:: yaml
303
304 Form:
305 part01:
306 key01: value
307 key02:
308 key03: value
309 part02:
310 __inheritances:
311 10: Form.part01
312
313 The configuration above results in:
314
315 .. code-block:: yaml
316
317 Form:
318 part01:
319 key01: value
320 key02:
321 key03: value
322 part02:
323 key01: value
324 key02:
325 key03: value
326
327 As you can see, ``part02`` inherited all of ``part01``'s properties.
328
329 .. code-block:: yaml
330
331 Form:
332 part01:
333 key: value
334 part02:
335 __inheritances:
336 10: Form.part01
337 key: 'value override'
338
339 The configuration above results in:
340
341 .. code-block:: yaml
342
343 Form:
344 part01:
345 key: value
346 part02:
347 key: 'value override'
348
349 EXT:form heavily uses the ``__inheritances`` operator, in particular, for
350 the definition of form elements. The following example shows you how to use
351 the operator to define a new form element which behaves like the parent
352 element but also has its own properties.
353
354 .. code-block:: yaml
355
356 TYPO3:
357 CMS:
358 Form:
359 prototypes:
360 standard:
361 formElementsDefinition:
362 GenderSelect:
363 __inheritances:
364 10: 'TYPO3.CMS.Form.prototypes.standard.formElementsDefinition.RadioButton'
365 renderingOptions:
366 templateName: 'RadioButton'
367 properties:
368 options:
369 f: 'Female'
370 m: 'Male'
371 u: 'Unicorn'
372 a: 'Alien'
373
374 The YAML configuration defines a new form element called ``GenderSelect``.
375 This element inherits its definition from the ``RadioButton`` element but
376 additionally ships four predefined options. Without any problems, the new
377 element can be used and overridden within the ``form definition``.
378
379 .. hint::
380
381 Currently, there is no built-in solution within the TYPO3 core to
382 preview the resulting/ final EXT:form YAML configuration. If you want
383 to check the configuration, there is a fishy way which you should never
384 implement on a production system.
385
386 Open the file ``typo3/sysext/form/Classes/Mvc/Configuration/ConfigurationManager.php::getConfigurationFromYamlFile()``
387 and add the following code before the ``return`` statement::
388
389 \TYPO3\CMS\Extbase\Utility\DebuggerUtility::var_dump($yamlSettings, 'form configuration', 9999);
390
391 Now open the ``Forms`` module in the backend or navigate to a page in
392 the frontend which contains a form. The DebuggerUtility will print the
393 final configuration directly to the screen.
394
395 It will probably take some time to fully understand the awesomeness of
396 this operator. If you are eager to learn more about this great instrument,
397 check out the unit tests defined in ``EXT:form/Tests/Unit/Mvc/Configuration/InheritancesResolverServiceTest.php``.
398
399
400 .. _concepts-configuration-prototypes:
401
402 Prototypes
403 ----------
404
405 Most of the configurational aspects of the form framework are defined
406 in so-called ``prototypes``. By default, EXT:form defines a prototype
407 named ``standard``. The definition of form elements - including their
408 rendering in the frontend, ``form editor`` and ``form plugin`` - reside
409 within those prototypes. As soon as you create a new form, the specific
410 form definition references such a prototype.
411
412 This allows you to do a lot of nifty stuff. Let your imagination run free.
413 For example:
414
415 - based on the referenced prototype, the same form can load
416
417 - ...varying templates
418 - ...varying ``form editor`` configurations
419 - ...varying ``form plugin`` finisher overrides
420
421 - within the ``form manager``, depending on the selected prototype
422
423 - ...varying ``form editor`` configurations can be loaded
424 - ...varying pre-configured form templates (boilerplates) can be chosen
425
426 - different prototypes can define different/ extended form elements and
427 display them in the frontend/ ``form editor`` accordingly
428
429 Check out the following use case to fully understand the concept behind
430 prototypes. Imagine that there are two defined prototypes: "noob" and
431 "poweruser".
432
433 .. t3-field-list-table::
434 :header-rows: 1
435
436 - :a:
437 :b: Prototype "noob"
438 :c: Prototype "poweruser"
439
440 - :a: **Available form elements within the ``form editor``**
441 :b: Text, Textarea
442 :c: No changes. Default behaviour.
443
444 - :a: **Available finisher within the ``form editor``**
445 :b: Only the email finisher is available. It offers a field for setting
446 the subject of the mail. All remaining fields are hidden and filled
447 with default values.
448 :c: No changes. Default behaviour.
449
450 - :a: **Finisher overrides within the ``form plugin``**
451 :b: It is not possible to override the finisher configuration.
452 :c: No changes. Default behaviour.