[TASK] Better example for FlashMessage finisher
[Packages/TYPO3.CMS.git] / typo3 / sysext / form / Documentation / I / ApiReference / Index.rst
1 .. include:: ../../Includes.txt
2
3
4 .. _apireference:
5
6 =============
7 API Reference
8 =============
9
10 This chapter is a complete reference of the API of the form framework. It
11 mainly addresses your concerns as a developer.
12
13
14 .. _apireference-frontendrendering:
15
16 Frontend rendering
17 ==================
18
19
20 .. _apireference-frontendrendering-fluidformrenderer:
21
22 TYPO3\\CMS\\Form\\Domain\\Renderer\\FluidFormRenderer
23 -----------------------------------------------------
24
25
26 .. _apireference-frontendrendering-fluidformrenderer-options:
27
28 Options
29 ^^^^^^^
30
31 The ``FluidFormRenderer`` uses some rendering options which are of particular importance,
32 as they determine how the form field is resolved to a path in the file system.
33
34 All rendering options are retrieved from the ``FormDefinition``, using the ``TYPO3\CMS\Form\Domain\Model\FormDefinition::getRenderingOptions()`` method.
35
36
37 .. _apireference-frontendrendering-fluidformrenderer-options-templaterootpaths:
38
39 templateRootPaths
40 +++++++++++++++++
41
42 Used to define several paths for templates, which will be tried in reversed order (the paths are searched from bottom to top).
43 The first folder where the desired template is found, is used. If the array keys are numeric, they are first sorted and then tried in reversed order.
44 Within this paths, fluid will search for a file which is named like the ``<formElementTypeIdentifier>``.
45
46 For example:
47
48 templateRootPaths.10 = EXT:form/Resources/Private/Frontend/Templates/
49 $renderable->getType() == 'Form'
50 Expected template file: EXT:form/Resources/Private/Frontend/Templates/Form.html
51
52 Only the root element (``FormDefinition``) has to be a template file. All child form elements are partials. By default, the root element is called ``Form``.
53
54 .. code-block:: yaml
55
56 TYPO3:
57 CMS:
58 Form:
59 prototypes:
60 standard:
61 formElementsDefinition:
62 Form:
63 renderingOptions:
64 templateRootPaths:
65 10: 'EXT:form/Resources/Private/Frontend/Templates/'
66
67
68 .. _apireference-frontendrendering-fluidformrenderer-options-layoutrootpaths:
69
70 layoutRootPaths
71 +++++++++++++++
72
73 Used to define several paths for layouts, which will be tried in reversed order (the paths are searched from bottom to top).
74 The first folder where the desired layout is found, is used. If the array keys are numeric, they are first sorted and then tried in reversed order.
75
76 .. code-block:: yaml
77
78 TYPO3:
79 CMS:
80 Form:
81 prototypes:
82 standard:
83 formElementsDefinition:
84 Form:
85 renderingOptions:
86 layoutRootPaths:
87 10: 'EXT:form/Resources/Private/Frontend/Layouts/'
88
89
90 .. _apireference-frontendrendering-fluidformrenderer-options-partialrootpaths:
91
92 partialRootPaths
93 ++++++++++++++++
94
95 Used to define several paths for partials, which will be tried in reversed order. The first folder where the desired partial is found, is used.
96 The keys of the array define the order.
97
98 Within this paths, fluid will search for a file which is named like the ``<formElementTypeIdentifier>``.
99
100 For example:
101
102 templateRootPaths.10 = EXT:form/Resources/Private/Frontend/Partials/
103 $renderable->getType() == 'Text'
104 Expected template file: EXT:form/Resources/Private/Frontend/Partials/Text.html
105
106 There is a setting available to set a custom partial name. Please read the section :ref:`templateName<apireference-frontendrendering-fluidformrenderer-options-templatename>`.
107
108 .. code-block:: yaml
109
110 TYPO3:
111 CMS:
112 Form:
113 prototypes:
114 standard:
115 formElementsDefinition:
116 Form:
117 renderingOptions:
118 partialRootPaths:
119 10: 'EXT:form/Resources/Private/Frontend/Partials/'
120
121
122 .. _apireference-frontendrendering-fluidformrenderer-options-templatename:
123
124 templateName
125 ++++++++++++
126
127 By default, the renderable type will be taken as the name for the partial.
128
129 For example:
130
131 partialRootPaths.10 = EXT:form/Resources/Private/Frontend/Partials/
132 $renderable->getType() == 'Text'
133 Expected partial file: EXT:form/Resources/Private/Frontend/Partials/Text.html
134
135 Set ``templateName`` to define a custom name which should be used instead.
136
137 For example:
138
139 $renderable->getTemplateName() == 'Text'
140 $renderable->getType() = Foo
141 Expected partial file: EXT:form/Resources/Private/Frontend/Partials/Text.html
142
143 .. code-block:: yaml
144
145 TYPO3:
146 CMS:
147 Form:
148 prototypes:
149 standard:
150 formElementsDefinition:
151 Foo:
152 renderingOptions:
153 templateName: 'Text'
154
155
156 .. _apireference-frontendrendering-renderviewHelper:
157
158 "render" viewHelper
159 -------------------
160
161 .. _apireference-frontendrendering-renderviewHelper-arguments:
162
163 Arguments
164 ^^^^^^^^^
165
166 .. _apireference-frontendrendering-renderviewHelper-factoryclass:
167
168 factoryClass
169 ++++++++++++
170
171 A class name of a ``FormFactory``.
172 This factory is used to create the ``TYPO3\CMS\Form\Domain\Model\FormDefinition`` which is the ``form definition`` Domain Model.
173 If no ``factoryClass`` argument is passed, the factory supplied by EXT:form ``TYPO3\CMS\Form\ Domain\Factory\ArrayFormFactory`` is used.
174 Another factory class is required if the form is to be generated programmatically.
175 To do this you must implement your own ``FormFactory`` in which your own form is generated programmatically and passes this class name to the ViewHelper.
176 This then renders the form.
177
178 .. code-block:: html
179
180 <formvh:render factoryClass="VENDOR\MySitePackage\Domain\Factory\CustomFormFactory" />
181
182
183 .. _apireference-frontendrendering-renderviewHelper-persistenceidentifier:
184
185 persistenceIdentifier
186 +++++++++++++++++++++
187
188 The ``form definition`` to be found under ``persistenceIdentifier``.
189 The PersistenceManager now loads the ``form definition`` which is found under ``persistenceIdentifier`` and passes this configuration to the ``factoryClass``.
190 In this case, the ``factoryClass`` will be given an empty configuration array (if ``overrideConfiguration`` is not specified).
191
192 .. code-block:: html
193
194 <formvh:render persistenceIdentifier="EXT:my_site_package/Resources/Private/Forms/SimpleContactForm.yaml" />
195
196
197 .. _apireference-frontendrendering-renderviewHelper-overrideconfiguration:
198
199 overrideConfiguration
200 +++++++++++++++++++++
201
202 A configuration to be superimposed can be entered here.
203 If a ``persistenceIdentifier`` is specified, the ``form definition`` which is found under ``persistenceIdentifier`` is loaded.
204 This configuration is then superimposed with ``overrideConfiguration``. This configuration is then passed to the ``factoryClass``.
205 If no ``persistenceIdentifier`` is specified, ``overrideConfiguration`` is passed directly to the ``factoryClass``.
206 This way a configuration can be given to a ``factoryClass`` implementation.
207
208
209 .. _apireference-frontendrendering-renderviewHelper-prototypename:
210
211 prototypeName
212 +++++++++++++
213
214 The name of the prototype, on which basis the ``factoryClass`` should create the form.
215 If nothing is specified, the configuration (``form definition`` or ``overrideConfiguration``) is searched for the prototy name.
216 If no specification exists, the standard prototype ``standard`` is used.
217
218
219
220 .. _apireference-frontendrendering-programmatically:
221
222 Build forms programmatically
223 ----------------------------
224
225 Implement a ``FormFactory`` and build the form::
226
227 declare(strict_types = 1);
228 namespace VENDOR\MySitePackage\Domain\Factory;
229
230 use TYPO3\CMS\Core\Utility\GeneralUtility;
231 use TYPO3\CMS\Extbase\Object\ObjectManager;
232 use TYPO3\CMS\Extbase\Validation\Validator\NotEmptyValidator;
233 use TYPO3\CMS\Extbase\Validation\Validator\StringLengthValidator;
234 use TYPO3\CMS\Form\Domain\Configuration\ConfigurationService;
235 use TYPO3\CMS\Form\Domain\Factory\AbstractFormFactory;
236 use TYPO3\CMS\Form\Domain\Model\FormDefinition;
237
238 class CustomFormFactory extends AbstractFormFactory
239 {
240
241 /**
242 * Build a FormDefinition.
243 * This example build a FormDefinition manually,
244 * so $configuration and $prototypeName are unused.
245 *
246 * @param array $configuration
247 * @param string $prototypeName
248 * @return FormDefinition
249 */
250 public function build(array $configuration, string $prototypeName = null): FormDefinition
251 {
252 $prototypeName = 'standard';
253 $configurationService = GeneralUtility::makeInstance(ObjectManager::class)->get(ConfigurationService::class);
254 $prototypeConfiguration = $configurationService->getPrototypeConfiguration($prototypeName);
255
256 $form = GeneralUtility::makeInstance(ObjectManager::class)->get(FormDefinition::class, 'MyCustomForm', $prototypeConfiguration);
257 $form->setRenderingOption('controllerAction', 'index');
258
259 $page1 = $form->createPage('page1');
260 $name = $page1->createElement('name', 'Text');
261 $name->setLabel('Name');
262 $name->addValidator(GeneralUtility::makeInstance(ObjectManager::class)->get(NotEmptyValidator::class));
263
264 $page2 = $form->createPage('page2');
265 $message = $page2->createElement('message', 'Textarea');
266 $message->setLabel('Message');
267 $message->addValidator(GeneralUtility::makeInstance(ObjectManager::class)->get(StringLengthValidator::class, ['minimum' => 5, 'maximum' => 20]));
268
269 $form->createFinisher('EmailToSender', [
270 'subject' => 'Hello',
271 'recipientAddress' => 'foo@example.com',
272 'senderAddress' => 'bar@example.com',
273 ]);
274
275 $this->triggerFormBuildingFinished($form);
276 return $form;
277 }
278 }
279
280 Use this form within your fluid template.
281
282 .. code-block:: html
283
284 <formvh:render factoryClass="VENDOR\MySitePackage\Domain\Factory\CustomFormFactory" />
285
286
287 .. _apireference-frontendrendering-programmatically-commonapimethods:
288
289 Common API Methods
290 ^^^^^^^^^^^^^^^^^^
291
292
293 .. _apireference-frontendrendering-programmatically-commonapimethods-createpage:
294
295 TYPO3\\CMS\\Form\\Domain\\Model\\FormDefinition::createPage()
296 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
297
298 Create a page with the given $identifier and attach this page to the form.
299
300 - Create Page object based on the given $typeName
301 - set defaults inside the Page object
302 - attach Page object to this form
303 - return the newly created Page object
304
305 Signature::
306
307 public function createPage(string $identifier, string $typeName = 'Page'): Page;
308
309
310 .. _apireference-frontendrendering-programmatically-commonapimethods-createfinisher:
311
312 TYPO3\\CMS\\Form\\Domain\\Model\\FormDefinition::createFinisher()
313 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
314
315 Create a finisher with the given $identifier and given $options and attach this finisher to the form.
316
317 Signature::
318
319 public function createFinisher(string $finisherIdentifier, array $options = []): FinisherInterface;
320
321
322 .. _apireference-frontendrendering-programmatically-commonapimethods-page-createelement:
323
324 TYPO3\\CMS\\Form\\Domain\\Model\\FormElements\\Page::createElement()
325 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
326
327 Create a form element with the given $identifier and attach it to the page.
328
329 - Create Form Element object based on the given $typeName
330 - set defaults inside the Form Element (based on the parent form's field defaults)
331 - attach Form Element to the Page
332 - return the newly created Form Element object
333
334 Signature::
335
336 public function createElement(string $identifier, string $typeName): FormElementInterface;
337
338
339 .. _apireference-frontendrendering-programmatically-commonapimethods-section-createelement:
340
341 TYPO3\\CMS\\Form\\Domain\\Model\\FormElements\\Section::createElement()
342 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
343
344 Create a form element with the given $identifier and attach it to the section.
345
346 - Create Form Element object based on the given $typeName
347 - set defaults inside the Form Element (based on the parent form's field defaults)
348 - attach Form Element to the Section
349 - return the newly created Form Element object
350
351 Signature::
352
353 public function createElement(string $identifier, string $typeName): FormElementInterface;
354
355
356 .. _apireference-frontendrendering-programmatically-commonapimethods-abstractrenderable-createvalidator:
357
358 TYPO3\\CMS\\Form\\Domain\\Model\\Renderable\\AbstractFormElement::createValidator()
359 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
360
361 Create a validator for the element.
362 Mainly possible for
363
364 - TYPO3\\CMS\\Form\\Domain\\Model\\FormElements\\AdvancedPassword
365 - TYPO3\\CMS\\Form\\Domain\\Model\\FormElements\\GenericFormElement
366 - TYPO3\\CMS\\Form\\Domain\\Model\\FormElements\\DatePicker
367 - TYPO3\\CMS\\Form\\Domain\\Model\\FormElements\\FileUpload
368
369 Signature::
370
371 public function createValidator(string $validatorIdentifier, array $options = []);
372
373
374 .. _apireference-frontendrendering-programmatically-commonapimethods-initializeformelement:
375
376 initializeFormElement()
377 +++++++++++++++++++++++
378
379 Will be called as soon as the element is added to a form.
380 Possible for
381
382 - TYPO3\\CMS\\Form\\Domain\\Model\\FormElements\\Section
383 - TYPO3\\CMS\\Form\\Domain\\Model\\FormElements\\AdvancedPassword
384 - TYPO3\\CMS\\Form\\Domain\\Model\\FormElements\\GenericFormElement
385 - TYPO3\\CMS\\Form\\Domain\\Model\\FormElements\\DatePicker
386 - TYPO3\\CMS\\Form\\Domain\\Model\\FormElements\\FileUpload
387
388 Signature::
389
390 public function initializeFormElement();
391
392
393 You can use this method to prefill form element data for example from database tables.
394 All the classes you can see above extends from the ``TYPO3\CMS\Form\Domain\Model\FormElement\AbstractFormElement``.
395 ``AbstractFormElement`` implements this method like this::
396
397 public function initializeFormElement()
398 {
399 if (
400 isset($GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['initializeFormElement'])
401 && is_array($GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['initializeFormElement'])
402 ) {
403 foreach ($GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['initializeFormElement'] as $className) {
404 $hookObj = GeneralUtility::makeInstance($className);
405 if (method_exists($hookObj, 'initializeFormElement')) {
406 $hookObj->initializeFormElement(
407 $this
408 );
409 }
410 }
411 }
412 }
413
414 If you extend you custom implementation from ``AbstractFormElement`` (and you should do this),
415 it enables you to override the 'initializeFormElement' method within your custom implementation class.
416 If you do not call the parents 'initializeFormElement' then no hook will be thrown.
417
418 If your use case for a custom form element implementation means that you only want to initialize you form element
419 programmatically (e.g to get databasedata) and no other special things are to do, you might prefer the hook.
420 You only need a class which connects to this hook. Then detect the form element you wish to initialize.
421
422
423 .. _apireference-frontendrendering-programmatically-apimethods:
424
425 Further API Methods
426 ^^^^^^^^^^^^^^^^^^^
427
428
429 .. _apireference-frontendrendering-programmatically-apimethods-formruntime:
430
431 TYPO3\\CMS\\Form\\Domain\\Model\\FormRuntime
432 ++++++++++++++++++++++++++++++++++++++++++++
433
434
435 .. _apireference-frontendrendering-programmatically-apimethods-formruntime-overridecurrentpage:
436
437 overrideCurrentPage()
438 '''''''''''''''''''''
439
440 Override the current page taken from the request, rendering the page with index $pageIndex instead.
441 This is typically not needed in production code.
442 You might prefer the hook :ref:`afterInitializeCurrentPage <apireference-frontendrendering-runtimemanipulation-hooks-afterinitializecurrentpage>`
443
444 Signature::
445
446 public function overrideCurrentPage(int $pageIndex);
447
448 Example::
449
450 $form = $formDefinition->bind($this->request, $this->response);
451 $form->overrideCurrentPage($pageIndex);
452
453
454 .. _apireference-frontendrendering-programmatically-apimethods-formruntime-render:
455
456 render()
457 ''''''''
458
459 Render the form.
460
461 Signature::
462
463 public function render();
464
465
466 .. _apireference-frontendrendering-programmatically-apimethods-formruntime-getidentifier:
467 .. include:: RootRenderableInterface/getIdentifier.rst
468
469 .. _apireference-frontendrendering-programmatically-apimethods-formruntime-getrequest:
470
471 getRequest()
472 ''''''''''''
473
474 Get the request this object is bound to.
475 This is mostly relevant inside Finishers, where you f.e. want to redirect the user to another page.
476
477 Signature::
478
479 public function getRequest(): Request;
480
481
482 .. _apireference-frontendrendering-programmatically-apimethods-formruntime-getresponse:
483
484 getResponse()
485 '''''''''''''
486
487 Get the response this object is bound to.
488 This is mostly relevant inside Finishers, where you f.e. want to set response headers or output content.
489
490 Signature::
491
492 public function getResponse(): Response;
493
494
495 .. _apireference-frontendrendering-programmatically-apimethods-formruntime-getcurrentpage:
496
497 getCurrentPage()
498 ''''''''''''''''
499
500 Returns the currently selected page.
501
502 Signature::
503
504 public function getCurrentPage(): Page;
505
506
507 .. _apireference-frontendrendering-programmatically-apimethods-formruntime-getpreviouspage:
508
509 getPreviousPage()
510 '''''''''''''''''
511
512 Returns the previous page of the currently selected one or NULL if there is no previous page.
513
514 Signature::
515
516 public function getPreviousPage();
517
518
519 .. _apireference-frontendrendering-programmatically-apimethods-formruntime-getnextpage:
520
521 getNextPage()
522 '''''''''''''
523
524 Returns the next page of the currently selected one or NULL if there is no next page.
525
526 Signature::
527
528 public function getNextPage();
529
530
531 .. _apireference-frontendrendering-programmatically-apimethods-formruntime-gettype:
532 .. include:: RootRenderableInterface/getType.rst
533
534
535 .. _apireference-frontendrendering-programmatically-apimethods-formruntime-getelementvalue:
536
537 getElementValue()
538 '''''''''''''''''
539
540 Returns the value of the specified element.
541
542 Signature::
543
544 public function getElementValue(string $identifier);
545
546
547 .. _apireference-frontendrendering-programmatically-apimethods-formruntime-getpages:
548
549 getPages()
550 ''''''''''
551
552 Return the form's pages in the correct order.
553
554 Signature::
555
556 public function getPages(): array;
557
558
559 .. _apireference-frontendrendering-programmatically-apimethods-formruntime-getrenderingoptions:
560 .. include:: RootRenderableInterface/getRenderingOptions.rst
561
562 .. _apireference-frontendrendering-programmatically-apimethods-formruntime-getrendererclassname:
563 .. include:: RootRenderableInterface/getRendererClassName.rst
564
565 .. _apireference-frontendrendering-programmatically-apimethods-formruntime-getlabel:
566 .. include:: RootRenderableInterface/getLabel.rst
567
568 .. _apireference-frontendrendering-programmatically-apimethods-formruntime-gettemplatename:
569 .. include:: RenderableInterface/getTemplateName.rst
570
571 .. _apireference-frontendrendering-programmatically-apimethods-formruntime-getformdefinition:
572
573 getFormDefinition()
574 '''''''''''''''''''
575
576 Get the underlying form definition from the runtime.
577
578 Signature::
579
580 public function getFormDefinition(): FormDefinition;
581
582
583 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition:
584
585 TYPO3\\CMS\\Form\\Domain\\Model\\FormDefinition
586 +++++++++++++++++++++++++++++++++++++++++++++++
587
588 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-addpage:
589
590 addPage()
591 '''''''''
592
593 Add a new page at the end of the form.
594 Instead of this method, you should use ``createPage`` instead.
595
596 Signature::
597
598 public function addPage(Page $page);
599
600
601 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-createpage:
602
603 createPage()
604 ''''''''''''
605
606 Create a page with the given $identifier and attach this page to the form.
607
608 - Create Page object based on the given $typeName
609 - set defaults inside the Page object
610 - attach Page object to this form
611 - return the newly created Page object
612
613 Signature::
614
615 public function createPage(string $identifier, string $typeName = 'Page'): Page;
616
617
618 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-getpages:
619
620 getPages()
621 ''''''''''
622
623 Return the form's pages in the correct order.
624
625 Signature::
626
627 public function getPages(): array;
628
629
630 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-haspagewithindex:
631
632 hasPageWithIndex()
633 ''''''''''''''''''
634
635 Check whether a page with the given $index exists.
636
637 Signature::
638
639 public function hasPageWithIndex(int $index): bool;
640
641
642 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-getpagebyindex:
643
644 getPageByIndex()
645 ''''''''''''''''
646
647 Get the page with the passed index. The first page has index zero.
648 If page at $index does not exist, an exception is thrown.
649
650 Signature::
651
652 public function getPageByIndex(int $index);
653
654
655 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-addfinisher:
656
657 addFinisher()
658 '''''''''''''
659
660 Adds the specified finisher to the form.
661 Instead of this method, you should use ``createFinisher`` instead.
662
663 Signature::
664
665 public function addFinisher(FinisherInterface $finisher);
666
667
668 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-createfinisher:
669
670 createFinisher()
671 ''''''''''''''''
672
673 Create a finisher with the given $identifier and given $options and attach this finisher to the form.
674
675 Signature::
676
677 public function createFinisher(string $finisherIdentifier, array $options = []): FinisherInterface;
678
679 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-getfinishers:
680
681 getFinishers()
682 ''''''''''''''
683
684 Gets all finishers of the form.
685
686 Signature::
687
688 public function getFinishers(): array;
689
690
691 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-getelementbyidentifier:
692
693 getElementByIdentifier()
694 ''''''''''''''''''''''''
695
696 Get a form element by its identifier.
697 If identifier does not exist, returns NULL.
698
699 Signature::
700
701 public function getElementByIdentifier(string $elementIdentifier);
702
703
704 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-movepageafter:
705
706 movePageAfter()
707 '''''''''''''''
708
709 Move $pageToMove after $referencePage.
710
711 Signature::
712
713 public function movePageAfter(Page $pageToMove, Page $referencePage);
714
715
716 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-removepage:
717
718 removePage()
719 ''''''''''''
720
721 Remove $pageToRemove from the form.
722
723 Signature::
724
725 public function removePage(Page $pageToRemove);
726
727
728 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-bind:
729
730 bind()
731 ''''''
732
733 Bind the current request and response to this form instance, effectively creating a new "instance" of the Form.
734
735 Signature::
736
737 public function bind(Request $request, Response $response): FormRuntime;
738
739
740 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-getprocessingrule:
741
742 getProcessingRule()
743 '''''''''''''''''''
744
745 Get the processing rule which contains information for property mappings and validations.
746
747 Signature::
748
749 public function getProcessingRule(string $propertyPath): ProcessingRule;
750
751
752 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-gettype:
753 .. include:: RootRenderableInterface/getType.rst
754
755 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-getidentifier:
756 .. include:: RootRenderableInterface/getIdentifier.rst
757
758 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-setidentifier:
759 .. include:: AbstractRenderable/setIdentifier.rst
760
761 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-setoptions:
762 .. include:: AbstractRenderable/setOptions.rst
763
764 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-addvalidator:
765 .. include:: FormElementInterface/addValidator.rst
766
767 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-setdatatype:
768 .. include:: FormElementInterface/setDataType.rst
769
770 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-getrendererclassname:
771 .. include:: RootRenderableInterface/getRendererClassName.rst
772
773 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-setrendererclassname:
774
775 setRendererClassName()
776 ''''''''''''''''''''''
777
778 Set the renderer class name.
779
780 Signature::
781
782 public function setRendererClassName(string $rendererClassName);
783
784
785 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-getrenderingoptions:
786 .. include:: RootRenderableInterface/getRenderingOptions.rst
787
788 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-setrenderingoption:
789 .. include:: FormElementInterface/setRenderingOption.rst
790
791 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-getparentrenderable:
792 .. include:: RenderableInterface/getParentRenderable.rst
793
794 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-setparentrenderable:
795 .. include:: RenderableInterface/setParentRenderable.rst
796
797 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-getrootform:
798 .. include:: AbstractRenderable/getRootForm.rst
799
800 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-getlabel:
801 .. include:: RootRenderableInterface/getLabel.rst
802
803 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-setlabel:
804 .. include:: AbstractRenderable/setLabel.rst
805
806 .. _apireference-frontendrendering-programmatically-apimethods-formdefinition-gettemplatename:
807 .. include:: RenderableInterface/getTemplateName.rst
808
809
810 .. _apireference-frontendrendering-programmatically-apimethods-page:
811
812 TYPO3\\CMS\\Form\\Domain\\Model\\FormElements\\Page
813 +++++++++++++++++++++++++++++++++++++++++++++++++++
814
815 .. _apireference-frontendrendering-programmatically-apimethods-page-getelements:
816 .. include:: AbstractSection/getElements.rst
817
818 .. _apireference-frontendrendering-programmatically-apimethods-page-getelementsrecursively:
819 .. include:: AbstractSection/getElementsRecursively.rst
820
821 .. _apireference-frontendrendering-programmatically-apimethods-page-addelement:
822 .. include:: AbstractSection/addElement.rst
823
824 .. _apireference-frontendrendering-programmatically-apimethods-page-createelement:
825
826 createElement()
827 '''''''''''''''
828
829 Create a form element with the given $identifier and attach it to the page.
830
831 - Create Form Element object based on the given $typeName
832 - set defaults inside the Form Element (based on the parent form's field defaults)
833 - attach Form Element to the Page
834 - return the newly created Form Element object
835
836 Signature::
837
838 public function createElement(string $identifier, string $typeName): FormElementInterface;
839
840
841 .. _apireference-frontendrendering-programmatically-apimethods-page-moveelementbefore:
842 .. include:: AbstractSection/moveElementBefore.rst
843
844 .. _apireference-frontendrendering-programmatically-apimethods-page-moveelementafter:
845 .. include:: AbstractSection/moveElementAfter.rst
846
847 .. _apireference-frontendrendering-programmatically-apimethods-page-removeelement:
848 .. include:: AbstractSection/removeElement.rst
849
850 .. _apireference-frontendrendering-programmatically-apimethods-page-gettype:
851 .. include:: RootRenderableInterface/getType.rst
852
853 .. _apireference-frontendrendering-programmatically-apimethods-page-getidentifier:
854 .. include:: RootRenderableInterface/getIdentifier.rst
855
856 .. _apireference-frontendrendering-programmatically-apimethods-page-setidentifier:
857 .. include:: AbstractRenderable/setIdentifier.rst
858
859 .. _apireference-frontendrendering-programmatically-apimethods-page-setoptions:
860 .. include:: AbstractRenderable/setOptions.rst
861
862 .. _apireference-frontendrendering-programmatically-apimethods-page-addvalidator:
863 .. include:: FormElementInterface/addValidator.rst
864
865 .. _apireference-frontendrendering-programmatically-apimethods-page-createvalidator:
866 .. include:: FormElementInterface/createValidator.rst
867
868 .. _apireference-frontendrendering-programmatically-apimethods-page-setdatatype:
869 .. include:: FormElementInterface/setDataType.rst
870
871 .. _apireference-frontendrendering-programmatically-apimethods-page-getrendererclassname:
872 .. include:: RootRenderableInterface/getRendererClassName.rst
873
874 .. _apireference-frontendrendering-programmatically-apimethods-page-getrenderingoptions:
875 .. include:: RootRenderableInterface/getRenderingOptions.rst
876
877 .. _apireference-frontendrendering-programmatically-apimethods-page-setrenderingoption:
878 .. include:: FormElementInterface/setRenderingOption.rst
879
880 .. _apireference-frontendrendering-programmatically-apimethods-page-getparentrenderable:
881 .. include:: RenderableInterface/getParentRenderable.rst
882
883 .. _apireference-frontendrendering-programmatically-apimethods-page-setparentrenderable:
884 .. include:: RenderableInterface/setParentRenderable.rst
885
886 .. _apireference-frontendrendering-programmatically-apimethods-page-getrootform:
887 .. include:: AbstractRenderable/getRootForm.rst
888
889 .. _apireference-frontendrendering-programmatically-apimethods-page-getlabel:
890 .. include:: RootRenderableInterface/getLabel.rst
891
892 .. _apireference-frontendrendering-programmatically-apimethods-page-setlabel:
893 .. include:: AbstractRenderable/setLabel.rst
894
895 .. _apireference-frontendrendering-programmatically-apimethods-page-gettemplatename:
896 .. include:: RenderableInterface/getTemplateName.rst
897
898
899 .. _apireference-frontendrendering-programmatically-apimethods-section:
900
901 TYPO3\\CMS\\Form\\Domain\\Model\\FormElements\\Section
902 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
903
904 .. _apireference-frontendrendering-programmatically-apimethods-section-initializeformelement:
905 .. include:: FormElementInterface/initializeFormElement.rst
906
907 .. _apireference-frontendrendering-programmatically-apimethods-section-getuniqueidentifier:
908 .. include:: FormElementInterface/getUniqueIdentifier.rst
909
910 .. _apireference-frontendrendering-programmatically-apimethods-section-setproperty:
911 .. include:: FormElementInterface/setProperty.rst
912
913 .. _apireference-frontendrendering-programmatically-apimethods-section-getproperties:
914 .. include:: FormElementInterface/getProperties.rst
915
916 .. _apireference-frontendrendering-programmatically-apimethods-section-isrequired:
917 .. include:: FormElementInterface/isRequired.rst
918
919 .. _apireference-frontendrendering-programmatically-apimethods-section-getelements:
920 .. include:: AbstractSection/getElements.rst
921
922 .. _apireference-frontendrendering-programmatically-apimethods-section-getelementsrecursively:
923 .. include:: AbstractSection/getElementsRecursively.rst
924
925 .. _apireference-frontendrendering-programmatically-apimethods-section-addelement:
926 .. include:: AbstractSection/addElement.rst
927
928 .. _apireference-frontendrendering-programmatically-apimethods-section-createelement:
929
930 createElement()
931 '''''''''''''''
932
933 Create a form element with the given $identifier and attach it to the section.
934
935 - Create Form Element object based on the given $typeName
936 - set defaults inside the Form Element (based on the parent form's field defaults)
937 - attach Form Element to the Section
938 - return the newly created Form Element object
939
940 Signature::
941
942 public function createElement(string $identifier, string $typeName): FormElementInterface;
943
944
945 .. _apireference-frontendrendering-programmatically-apimethods-section-moveelementbefore:
946 .. include:: AbstractSection/moveElementBefore.rst
947
948 .. _apireference-frontendrendering-programmatically-apimethods-section-moveelementafter:
949 .. include:: AbstractSection/moveElementAfter.rst
950
951 .. _apireference-frontendrendering-programmatically-apimethods-section-removeelement:
952 .. include:: AbstractSection/removeElement.rst
953
954 .. _apireference-frontendrendering-programmatically-apimethods-section-gettype:
955 .. include:: RootRenderableInterface/getType.rst
956
957 .. _apireference-frontendrendering-programmatically-apimethods-section-getidentifier:
958 .. include:: RootRenderableInterface/getIdentifier.rst
959
960 .. _apireference-frontendrendering-programmatically-apimethods-section-setidentifier:
961 .. include:: AbstractRenderable/setIdentifier.rst
962
963 .. _apireference-frontendrendering-programmatically-apimethods-section-setoptions:
964 .. include:: AbstractRenderable/setOptions.rst
965
966 .. _apireference-frontendrendering-programmatically-apimethods-section-addvalidator:
967 .. include:: FormElementInterface/addValidator.rst
968
969 .. _apireference-frontendrendering-programmatically-apimethods-section-createvalidator:
970 .. include:: FormElementInterface/createValidator.rst
971
972 .. _apireference-frontendrendering-programmatically-apimethods-section-setdatatype:
973 .. include:: FormElementInterface/setDataType.rst
974
975 .. _apireference-frontendrendering-programmatically-apimethods-section-getrendererclassname:
976 .. include:: RootRenderableInterface/getRendererClassName.rst
977
978 .. _apireference-frontendrendering-programmatically-apimethods-section-getrenderingoptions:
979 .. include:: RootRenderableInterface/getRenderingOptions.rst
980
981 .. _apireference-frontendrendering-programmatically-apimethods-section-setrenderingoption:
982 .. include:: FormElementInterface/setRenderingOption.rst
983
984 .. _apireference-frontendrendering-programmatically-apimethods-section-getparentrenderable:
985 .. include:: RenderableInterface/getParentRenderable.rst
986
987 .. _apireference-frontendrendering-programmatically-apimethods-section-setparentrenderable:
988 .. include:: RenderableInterface/setParentRenderable.rst
989
990 .. _apireference-frontendrendering-programmatically-apimethods-section-getrootform:
991 .. include:: AbstractRenderable/getRootForm.rst
992
993 .. _apireference-frontendrendering-programmatically-apimethods-section-getlabel:
994 .. include:: RootRenderableInterface/getLabel.rst
995
996 .. _apireference-frontendrendering-programmatically-apimethods-section-setlabel:
997 .. include:: AbstractRenderable/setLabel.rst
998
999 .. _apireference-frontendrendering-programmatically-apimethods-section-gettemplatename:
1000 .. include:: RenderableInterface/getTemplateName.rst
1001
1002
1003 .. _apireference-frontendrendering-programmatically-apimethods-abstractformelement:
1004
1005 TYPO3\\CMS\\Form\\Domain\\Model\\FormElements\\AbstractFormElement
1006 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1007
1008 The following classes extends from ``AbstractFormElement`` and therefore contain the following API methods.
1009
1010 - TYPO3\\CMS\\Form\\Domain\\Model\\FormElements\\AdvancedPassword
1011 - TYPO3\\CMS\\Form\\Domain\\Model\\FormElements\\GenericFormElement
1012 - TYPO3\\CMS\\Form\\Domain\\Model\\FormElements\\DatePicker
1013 - TYPO3\\CMS\\Form\\Domain\\Model\\FormElements\\FileUpload
1014
1015
1016 .. _apireference-frontendrendering-programmatically-apimethods-abstractformelement-initializeformelement:
1017 .. include:: FormElementInterface/initializeFormElement.rst
1018
1019 .. _apireference-frontendrendering-programmatically-apimethods-abstractformelement-getuniqueidentifier:
1020 .. include:: FormElementInterface/getUniqueIdentifier.rst
1021
1022 .. _apireference-frontendrendering-programmatically-apimethods-abstractformelement-getdefaultvalue:
1023 .. include:: FormElementInterface/getDefaultValue.rst
1024
1025 .. _apireference-frontendrendering-programmatically-apimethods-abstractformelement-setdefaultvalue:
1026 .. include:: FormElementInterface/setDefaultValue.rst
1027
1028 .. _apireference-frontendrendering-programmatically-apimethods-abstractformelement-setproperty:
1029 .. include:: FormElementInterface/setProperty.rst
1030
1031 .. _apireference-frontendrendering-programmatically-apimethods-abstractformelement-getproperties:
1032 .. include:: FormElementInterface/getProperties.rst
1033
1034 .. _apireference-frontendrendering-programmatically-apimethods-abstractformelement-isrequired:
1035 .. include:: FormElementInterface/isRequired.rst
1036
1037 .. _apireference-frontendrendering-programmatically-apimethods-abstractformelement-gettype:
1038 .. include:: RootRenderableInterface/getType.rst
1039
1040 .. _apireference-frontendrendering-programmatically-apimethods-abstractformelement-getidentifier:
1041 .. include:: RootRenderableInterface/getIdentifier.rst
1042
1043 .. _apireference-frontendrendering-programmatically-apimethods-abstractformelement-setidentifier:
1044 .. include:: AbstractRenderable/setIdentifier.rst
1045
1046 .. _apireference-frontendrendering-programmatically-apimethods-abstractformelement-setoptions:
1047 .. include:: AbstractRenderable/setOptions.rst
1048
1049 .. _apireference-frontendrendering-programmatically-apimethods-abstractformelement-addvalidator:
1050 .. include:: FormElementInterface/addValidator.rst
1051
1052 .. _apireference-frontendrendering-programmatically-apimethods-abstractformelement-createvalidator:
1053 .. include:: FormElementInterface/createValidator.rst
1054
1055 .. _apireference-frontendrendering-programmatically-apimethods-abstractformelement-setdatatype:
1056 .. include:: FormElementInterface/setDataType.rst
1057
1058 .. _apireference-frontendrendering-programmatically-apimethods-abstractformelement-getrendererclassname:
1059 .. include:: RootRenderableInterface/getRendererClassName.rst
1060
1061 .. _apireference-frontendrendering-programmatically-apimethods-abstractformelement-getrenderingoptions:
1062 .. include:: RootRenderableInterface/getRenderingOptions.rst
1063
1064 .. _apireference-frontendrendering-programmatically-apimethods-abstractformelement-setrenderingoption:
1065 .. include:: FormElementInterface/setRenderingOption.rst
1066
1067 .. _apireference-frontendrendering-programmatically-apimethods-abstractformelement-getparentrenderable:
1068 .. include:: RenderableInterface/getParentRenderable.rst
1069
1070 .. _apireference-frontendrendering-programmatically-apimethods-abstractformelement-setparentrenderable:
1071 .. include:: RenderableInterface/setParentRenderable.rst
1072
1073 .. _apireference-frontendrendering-programmatically-apimethods-abstractformelement-getrootform:
1074 .. include:: AbstractRenderable/getRootForm.rst
1075
1076 .. _apireference-frontendrendering-programmatically-apimethods-abstractformelement-getlabel:
1077 .. include:: RootRenderableInterface/getLabel.rst
1078
1079 .. _apireference-frontendrendering-programmatically-apimethods-abstractformelement-setlabel:
1080 .. include:: AbstractRenderable/setLabel.rst
1081
1082 .. _apireference-frontendrendering-programmatically-apimethods-abstractformelement-gettemplatename:
1083 .. include:: RenderableInterface/getTemplateName.rst
1084
1085
1086 .. _apireference-frontendrendering-programmatically-apimethods-abstractfinisher:
1087
1088 TYPO3\\CMS\\Form\\Domain\\Finishers\\AbstractFinisher
1089 +++++++++++++++++++++++++++++++++++++++++++++++++++++
1090
1091 The following classes extends from ``AbstractFinisher`` and therefore contain the following API methods.
1092
1093 - TYPO3\\CMS\\Form\\Domain\\Finishers\\ClosureFinisher
1094 - TYPO3\\CMS\\Form\\Domain\\Finishers\\ConfirmationFinisher
1095 - TYPO3\\CMS\\Form\\Domain\\Finishers\\DeleteUploadsFinisher
1096 - TYPO3\\CMS\\Form\\Domain\\Finishers\\EmailFinisher
1097 - TYPO3\\CMS\\Form\\Domain\\Finishers\\FlashMessageFinisher
1098 - TYPO3\\CMS\\Form\\Domain\\Finishers\\RedirectFinisher
1099 - TYPO3\\CMS\\Form\\Domain\\Finishers\\SaveToDatabaseFinisher
1100
1101
1102 .. _apireference-frontendrendering-programmatically-apimethods-abstractfinisher-execute:
1103
1104 execute()
1105 '''''''''
1106
1107 Executes the finisher. ``AbstractFinisher::execute()`` call ``$this->executeInternal()`` at the end. Own finisher
1108 implementations which extends from ``AbstractFinisher:`` must start their own logic within ``executeInternal()``.
1109
1110 Signature::
1111
1112 public function execute(FinisherContext $finisherContext);
1113
1114
1115 .. _apireference-frontendrendering-programmatically-apimethods-abstractfinisher-setoptions:
1116
1117 setOptions()
1118 ''''''''''''
1119
1120 Set the finisher options. Instead of directly accessing them, you should rather use ``parseOption()``.
1121
1122 Signature::
1123
1124 public function setOptions(array $options);
1125
1126
1127 .. _apireference-frontendrendering-programmatically-apimethods-abstractfinisher-setoption:
1128
1129 setOption()
1130 '''''''''''
1131
1132 Sets a single finisher option.
1133
1134 Signature::
1135
1136 public function setOption(string $optionName, $optionValue);
1137
1138
1139 .. _apireference-frontendrendering-programmatically-apimethods-abstractfinisher-parseoption:
1140
1141 parseOption()
1142 '''''''''''''
1143
1144 Please read :ref:`Accessing finisher options<concepts-finishers-customfinisherimplementations-accessingoptions>`
1145
1146 Signature::
1147
1148 protected function parseOption(string $optionName);
1149
1150
1151 .. _apireference-frontendrendering-programmatically-apimethods-finishercontext:
1152
1153 TYPO3\\CMS\\Form\\Domain\\Finishers\\FinisherContext
1154 ++++++++++++++++++++++++++++++++++++++++++++++++++++
1155
1156 .. _apireference-frontendrendering-programmatically-apimethods-finishercontext-cancel:
1157
1158 cancel()
1159 ''''''''
1160
1161 Cancels the finisher invocation after the current finisher.
1162
1163 Signature::
1164
1165 public function cancel();
1166
1167
1168 .. _apireference-frontendrendering-programmatically-apimethods-finishercontext-getformruntime:
1169
1170 getFormRuntime()
1171 ''''''''''''''''
1172
1173 The Form Runtime that is associated with the current finisher.
1174
1175 Signature::
1176
1177 public function getFormRuntime(): FormRuntime;
1178
1179
1180 .. _apireference-frontendrendering-programmatically-apimethods-finishercontext-getformvalues:
1181
1182 getFormValues()
1183 '''''''''''''''
1184
1185 The values of the submitted form (after validation and property mapping).
1186
1187 Signature::
1188
1189 public function getFormValues(): array;
1190
1191
1192 .. _apireference-frontendrendering-programmatically-apimethods-finishercontext-getcontrollercontext:
1193
1194 getControllerContext()
1195 ''''''''''''''''''''''
1196
1197 Returns the current ControllerContext.
1198
1199 Signature::
1200
1201 public function getControllerContext(): ControllerContext;
1202
1203
1204 .. _apireference-frontendrendering-programmatically-apimethods-finishercontext-getfinishervariableprovider:
1205
1206 getFinisherVariableProvider()
1207 '''''''''''''''''''''''''''''
1208
1209 Returns the current FinisherVariableProvider.
1210
1211 Signature::
1212
1213 public function getFinisherVariableProvider(): FinisherVariableProvider;
1214
1215
1216 .. _apireference-frontendrendering-programmatically-apimethods-finishervariableprovider:
1217
1218 TYPO3\\CMS\\Form\\Domain\\Finishers\\FinisherVariableProvider
1219 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1220
1221 Please read :ref:`Share data between finishers<concepts-finishers-customfinisherimplementations-finishercontext-sharedatabetweenfinishers>`
1222
1223 .. _apireference-frontendrendering-programmatically-apimethods-finishervariableprovider-add:
1224
1225 add()
1226 '''''
1227
1228 Add a variable to the finisher variable provider.
1229 In case the value is already inside, it is silently overridden.
1230
1231 Signature::
1232
1233 public function add(string $finisherIdentifier, string $key, $value);
1234
1235
1236 .. _apireference-frontendrendering-programmatically-apimethods-finishervariableprovider-get:
1237
1238 get()
1239 '''''
1240
1241 Gets a variable from the finisher variable provider.
1242
1243 Signature::
1244
1245 public function get(string $finisherIdentifier, string $key, $default = null);
1246
1247
1248 .. _apireference-frontendrendering-programmatically-apimethods-finishervariableprovider-exists:
1249
1250 exists()
1251 ''''''''
1252
1253 Determine whether there is a variable stored for the given key.
1254
1255 Signature::
1256
1257 public function exists($finisherIdentifier, $key): bool;
1258
1259
1260 .. _apireference-frontendrendering-programmatically-apimethods-finishervariableprovider-remove:
1261
1262 remove()
1263 ''''''''
1264
1265 Remove a value from the finisher variable provider.
1266
1267 Signature::
1268
1269 public function remove(string $finisherIdentifier, string $key);
1270
1271
1272 .. _apireference-frontendrendering-programmatically-apimethods-configurationservice:
1273
1274 TYPO3\\CMS\\Form\\Domain\\Configuration\\ConfigurationService
1275 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1276
1277 .. _apireference-frontendrendering-programmatically-apimethods-configurationservice-getprototypeconfiguration:
1278
1279 getPrototypeConfiguration()
1280 '''''''''''''''''''''''''''
1281
1282 Get the configuration for a given $prototypeName
1283
1284 Signature::
1285
1286 public function getPrototypeConfiguration(string $prototypeName): array;
1287
1288
1289 .. _apireference-frontendrendering-programmatically-apimethods-abstractformfactory:
1290
1291 TYPO3\\CMS\\Form\\Domain\\Factory\\AbstractFormFactory
1292 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
1293
1294 .. _apireference-frontendrendering-programmatically-apimethods-abstractformfactory-triggerformbuildingfinished:
1295
1296 triggerFormBuildingFinished()
1297 '''''''''''''''''''''''''''''
1298
1299 Helper to be called by every ``FormFactory`` which extends from ``AbstractFormFactory`` after
1300 everything has been built to call the "afterBuildingFinished" hook on all form elements.
1301
1302 Signature::
1303
1304 protected function triggerFormBuildingFinished(FormDefinition $form);
1305
1306
1307 .. _apireference-frontendrendering-programmatically-apimethods-formfactoryinterface:
1308
1309 TYPO3\\CMS\\Form\\Domain\\Factory\\FormFactoryInterface
1310 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
1311
1312 .. _apireference-frontendrendering-programmatically-apimethods-formfactoryinterface-build:
1313
1314 build()
1315 '''''''
1316
1317 Build a form definition, depending on some configuration.
1318
1319 Signature::
1320
1321 public function build(array $configuration, string $prototypeName = null): FormDefinition;
1322
1323
1324 .. _apireference-frontendrendering-programmatically-apimethods-rendererinterface:
1325
1326 TYPO3\\CMS\\Form\\Domain\\Renderer\\RendererInterface
1327 +++++++++++++++++++++++++++++++++++++++++++++++++++++
1328
1329 .. _apireference-frontendrendering-programmatically-apimethods-rendererinterface-setcontrollercontext:
1330
1331 setControllerContext()
1332 ''''''''''''''''''''''
1333
1334 Set the controller context which should be used::
1335
1336 public function setControllerContext(ControllerContext $controllerContext);
1337
1338
1339 .. _apireference-frontendrendering-programmatically-apimethods-rendererinterface-render:
1340
1341 render()
1342 ''''''''
1343
1344 Renders the FormDefinition. This method is expected to call the ``beforeRendering`` hook on each form element::
1345
1346 public function render(): string;
1347
1348
1349 .. _apireference-frontendrendering-programmatically-apimethods-rendererinterface-setformruntime:
1350
1351 setFormRuntime()
1352 ''''''''''''''''
1353
1354 Set the current ``FormRuntime``::
1355
1356 public function setFormRuntime(FormRuntime $formRuntime);
1357
1358
1359 .. _apireference-frontendrendering-programmatically-apimethods-rendererinterface-getformruntime:
1360
1361 getFormRuntime()
1362 ''''''''''''''''
1363
1364 Get the current ``FormRuntime``::
1365
1366 public function getFormRuntime(): FormRuntime;
1367
1368
1369 .. _apireference-frontendrendering-runtimemanipulation:
1370
1371 Runtime manipulation
1372 --------------------
1373
1374 .. _apireference-frontendrendering-runtimemanipulation-hooks:
1375
1376 Hooks
1377 ^^^^^
1378
1379
1380 .. _apireference-frontendrendering-runtimemanipulation-hooks-initializeformelement:
1381
1382 initializeFormElement
1383 +++++++++++++++++++++
1384
1385 You can connect to this hook and initialize a form element without defining a
1386 custom implementaion to access the element's ``initializeFormElement`` method.
1387 You only need a class which connects to this hook. Then detect the form
1388 element you wish to initialize. For example, you can use this hook to prefill
1389 form element data from database tables. Note that this hook will be called
1390 **after** all properties from the prototype configuration are set in the form
1391 element but **before** the properties from the form definition are set in the
1392 form element. If you want to prefill form element data after the complete
1393 form element is configured you should use the
1394 :ref:`afterBuildingFinished<apireference-frontendrendering-runtimemanipulation-hooks-afterbuildingfinished>` hook.
1395
1396 The initializeFormElement hook is invoked by the methods ``TYPO3\CMS\Form\Domain\Model\FormElements\Page::createElement()``
1397 and ``TYPO3\CMS\Form\Domain\Model\FormElements\Section::createElement()``.
1398 That means the hook will **not** be triggered for ``Pages``. At this point
1399 you do not have access to submitted form element values.
1400
1401
1402 .. _apireference-frontendrendering-runtimemanipulation-hooks-initializeformelement-connect:
1403
1404 Connect to the hook
1405 '''''''''''''''''''
1406
1407 ::
1408
1409 $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['initializeFormElement'][<useATimestampAsKeyPlease>]
1410 = \VENDOR\YourNamespace\YourClass::class;
1411
1412
1413 .. note::
1414
1415 Wondering what :ref:`useATimestampAsKeyPlease<useATimestampAsKeyPlease>`
1416 means?
1417
1418
1419 .. _apireference-frontendrendering-runtimemanipulation-hooks-initializeformelement-use:
1420
1421 Use the hook
1422 ''''''''''''
1423
1424 ::
1425
1426 /**
1427 * @param \TYPO3\CMS\Form\Domain\Model\Renderable\RenderableInterface $renderable
1428 * @return void
1429 */
1430 public function initializeFormElement(\TYPO3\CMS\Form\Domain\Model\Renderable\RenderableInterface $renderable)
1431 {
1432 if ($renderable->getUniqueIdentifier() === 'contactForm-text-1') {
1433 $renderable->setDefaultValue('foo');
1434 }
1435 }
1436
1437
1438 .. _useATimestampAsKeyPlease:
1439
1440 What does <useATimestampAsKeyPlease> mean?
1441 ++++++++++++++++++++++++++++++++++++++++++
1442
1443 Timestamps are recommended for hooks such as those of the form framework, as
1444 seen in the following example::
1445
1446 $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['initializeFormElement'][<useATimestampAsKeyPlease>]
1447 = \VENDOR\YourNamespace\YourClass::class;
1448
1449
1450 Leaving the section ``<useATimestampAsKeyPlease>`` as is is not recommended.
1451 It does nothing except cause the extension to fail and an error message to be
1452 delivered. Nor should it be replaced with a function like time(), as the key
1453 should be unalterable. Instead, replace this section with the current UNIX
1454 timestamp the moment you are implementing the hook. Check out the following
1455 example::
1456
1457 $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['initializeFormElement'][1507018413]
1458 = \VENDOR\YourNamespace\YourClass::class;
1459
1460
1461 The purpose of timestamps is to prevent conflicts that arise when two or more
1462 extensions within one TYPO3 installation use identical keys (e.g.
1463 ``$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['initializeFormElement']['foo'])``.
1464 When timestamps are used, even a one-second difference in the time different
1465 hooks were connected ensures that one hook does not override the other.
1466
1467
1468 .. _apireference-frontendrendering-runtimemanipulation-hooks-beforeremovefromparentrenderable:
1469
1470 beforeRemoveFromParentRenderable
1471 ++++++++++++++++++++++++++++++++
1472
1473 This hook is invoked by the methods ``TYPO3\CMS\Form\Domain\Model\FormDefinition::removePage()``, ``TYPO3\CMS\Form\Domain\Model\FormElements\Page::removeElement()``
1474 and ``TYPO3\CMS\Form\Domain\Model\FormElements\Section::removeElement()``
1475
1476
1477 .. _apireference-frontendrendering-runtimemanipulation-hooks-beforeremovefromparentrenderable-connect:
1478
1479 Connect to the hook
1480 '''''''''''''''''''
1481
1482 ::
1483
1484 $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['beforeRemoveFromParentRenderable'][<useATimestampAsKeyPlease>]
1485 = \VENDOR\YourNamespace\YourClass::class;
1486
1487
1488 .. note::
1489
1490 Wondering what :ref:`useATimestampAsKeyPlease<useATimestampAsKeyPlease>`
1491 means?
1492
1493
1494 .. _apireference-frontendrendering-runtimemanipulation-hooks-beforeremovefromparentrenderable-use:
1495
1496 Use the hook
1497 ''''''''''''
1498
1499 ::
1500
1501 /**
1502 * @param \TYPO3\CMS\Form\Domain\Model\Renderable\RenderableInterface $renderable
1503 * @return void
1504 */
1505 public function beforeRemoveFromParentRenderable(\TYPO3\CMS\Form\Domain\Model\Renderable\RenderableInterface $renderable)
1506 {
1507 }
1508
1509
1510 .. _apireference-frontendrendering-runtimemanipulation-hooks-afterbuildingfinished:
1511
1512 afterBuildingFinished
1513 +++++++++++++++++++++
1514
1515 This hook is called for each form element after the class ``TYPO3\CMS\Form\Domain\Factory\ArrayFormFactory``
1516 has built the entire form. This hook is triggered just before the
1517 ``FormRuntime`` object is generated. At this point, no run-time information
1518 (e.g. assigned form values) is yet available. It can, for example, be used to
1519 generate new form elements within complex forms. The ``ArrayFormFactory`` is
1520 used by EXT:form via the ``RenderViewHelper`` to render forms using a ``form
1521 definition`` YAML file. Each form factory implementation must deal with the
1522 calling of this hook themselves. EXT:form itself uses this hook to initialize
1523 the property-mapper configuration for ``FileUpload`` elements.
1524
1525 .. _apireference-frontendrendering-runtimemanipulation-hooks-afterbuildingfinished-connect:
1526
1527 Connect to the hook
1528 '''''''''''''''''''
1529
1530 ::
1531
1532 $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['afterBuildingFinished'][<useATimestampAsKeyPlease>]
1533 = \VENDOR\YourNamespace\YourClass::class;
1534
1535
1536 .. note::
1537
1538 Wondering what :ref:`useATimestampAsKeyPlease<useATimestampAsKeyPlease>`
1539 means?
1540
1541
1542 .. _apireference-frontendrendering-runtimemanipulation-hooks-afterbuildingfinished-use:
1543
1544 Use the hook
1545 ''''''''''''
1546
1547 ::
1548
1549 /**
1550 * @param \TYPO3\CMS\Form\Domain\Model\Renderable\RenderableInterface $renderable
1551 * @return void
1552 */
1553 public function afterBuildingFinished(\TYPO3\CMS\Form\Domain\Model\Renderable\RenderableInterface $renderable)
1554 {
1555 }
1556
1557
1558 .. _apireference-frontendrendering-runtimemanipulation-hooks-afterinitializecurrentpage:
1559
1560 afterInitializeCurrentPage
1561 ++++++++++++++++++++++++++
1562
1563 EXT:form automatically detects the page that should be shown and allow users
1564 only to jump to the directly following (or previous) pages. This hook enables
1565 you to implement a custom behavior, for example pages that are shown only when
1566 other form elements have specific values.
1567
1568
1569 .. _apireference-frontendrendering-runtimemanipulation-hooks-afterinitializecurrentpage-connect:
1570
1571 Connect to the hook
1572 '''''''''''''''''''
1573
1574 ::
1575
1576 $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['afterInitializeCurrentPage'][<useATimestampAsKeyPlease>]
1577 = \VENDOR\YourNamespace\YourClass::class;
1578
1579
1580 .. note::
1581
1582 Wondering what :ref:`useATimestampAsKeyPlease<useATimestampAsKeyPlease>`
1583 means?
1584
1585
1586 .. _apireference-frontendrendering-runtimemanipulation-hooks-afterinitializecurrentpage-use:
1587
1588 Use the hook
1589 ''''''''''''
1590
1591 ::
1592
1593 /**
1594 * @param \TYPO3\CMS\Form\Domain\Runtime\FormRuntime $formRuntime
1595 * @param \TYPO3\CMS\Form\Domain\Model\Renderable\CompositeRenderableInterface $currentPage
1596 * @param null|\TYPO3\CMS\Form\Domain\Model\Renderable\CompositeRenderableInterface $lastPage
1597 * @param mixed $elementValue submitted value of the element *before post processing*
1598 * @return \TYPO3\CMS\Form\Domain\Model\Renderable\CompositeRenderableInterface
1599 */
1600 public function afterInitializeCurrentPage(\TYPO3\CMS\Form\Domain\Runtime\FormRuntime $formRuntime, \TYPO3\CMS\Form\Domain\Model\Renderable\CompositeRenderableInterface $currentPage, \TYPO3\CMS\Form\Domain\Model\Renderable\CompositeRenderableInterface $lastPage = null, array $requestArguments = []): \TYPO3\CMS\Form\Domain\Model\Renderable\CompositeRenderableInterface
1601 {
1602 return $currentPage;
1603 }
1604
1605
1606 .. _apireference-frontendrendering-runtimemanipulation-hooks-aftersubmit:
1607
1608 afterSubmit
1609 +++++++++++
1610
1611 You can use it for example for dynamic validations which depends on other submitted form element values.
1612 This hook is invoked by the ``FormRuntime`` for each form element **before** values are property mapped, validated and pushed within the FormRuntime's ``FormState``.
1613 If the first page is submitted at the first time you cannot access the form element values from the first page by just calling ``$formRuntime['<someOtherFormElementIdentifier>']`` to access
1614 the submitted form element values from the first page. In this case you can access the submitted raw data through ``$requestArguments``.
1615 EXT:form itself uses this hook to dynamically add validation errors for ``AdvancedPassword`` form elements.
1616
1617
1618 .. _apireference-frontendrendering-runtimemanipulation-hooks-aftersubmit-connect:
1619
1620 Connect to the hook
1621 '''''''''''''''''''
1622
1623 ::
1624
1625 $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['afterSubmit'][<useATimestampAsKeyPlease>]
1626 = \VENDOR\YourNamespace\YourClass::class;
1627
1628
1629 .. note::
1630
1631 Wondering what :ref:`useATimestampAsKeyPlease<useATimestampAsKeyPlease>`
1632 means?
1633
1634
1635 .. _apireference-frontendrendering-runtimemanipulation-hooks-aftersubmit-use:
1636
1637 Use the hook
1638 ''''''''''''
1639
1640 ::
1641
1642 /**
1643 * @param \TYPO3\CMS\Form\Domain\Runtime\FormRuntime $formRuntime
1644 * @param \TYPO3\CMS\Form\Domain\Model\Renderable\RenderableInterface $renderable
1645 * @param mixed $elementValue submitted value of the element *before post processing*
1646 * @param array $requestArguments submitted raw request values
1647 * @return void
1648 */
1649 public function afterSubmit(\TYPO3\CMS\Form\Domain\Runtime\FormRuntime $formRuntime, \TYPO3\CMS\Form\Domain\Model\Renderable\RenderableInterface $renderable, $elementValue, array $requestArguments = [])
1650 {
1651 return $elementValue;
1652 }
1653
1654
1655 .. _apireference-frontendrendering-runtimemanipulation-hooks-beforerendering:
1656
1657 beforeRendering
1658 +++++++++++++++
1659
1660 This is a hook that is invoked by the rendering system before the corresponding element is rendered.
1661 Use this to access previously submitted values and/or modify the ``FormRuntime`` before an element is outputted to the browser.
1662 This hook is called after all validations and property mappings are done.
1663
1664 .. _apireference-frontendrendering-runtimemanipulation-hooks-beforerendering-connect:
1665
1666 Connect to the hook
1667 '''''''''''''''''''
1668
1669 ::
1670
1671 $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['beforeRendering'][<useATimestampAsKeyPlease>]
1672 = \VENDOR\YourNamespace\YourClass::class;
1673
1674
1675 .. note::
1676
1677 Wondering what :ref:`useATimestampAsKeyPlease<useATimestampAsKeyPlease>`
1678 means?
1679
1680
1681 .. _apireference-frontendrendering-runtimemanipulation-hooks-beforerendering-use:
1682
1683 Use the hook
1684 ''''''''''''
1685
1686 ::
1687
1688 /**
1689 * @param \TYPO3\CMS\Form\Domain\Runtime\FormRuntime $formRuntime
1690 * @param \TYPO3\CMS\Form\Domain\Model\Renderable\RootRenderableInterface $renderable
1691 * @return void
1692 */
1693 public function beforeRendering(\TYPO3\CMS\Form\Domain\Runtime\FormRuntime $formRuntime, \TYPO3\CMS\Form\Domain\Model\Renderable\RootRenderableInterface $renderable)
1694 {
1695 }
1696
1697
1698 .. _apireference-finisheroptions:
1699
1700 Finisher Options
1701 ================
1702
1703 .. _apireference-finisheroptions-closurefinisher:
1704
1705 Closure finisher
1706 ----------------
1707
1708 This finisher can only be used in programmatically-created forms. It makes it
1709 possible to execute one's own finisher code without having to implement/
1710 declare this finisher.
1711
1712 Usage through code::
1713
1714 $closureFinisher = $this->objectManager->get(ClosureFinisher::class);
1715 $closureFinisher->setOption('closure', function($finisherContext) {
1716 $formRuntime = $finisherContext->getFormRuntime();
1717 // ...
1718 });
1719 $formDefinition->addFinisher($closureFinisher);
1720
1721
1722 .. _apireference-finisheroptions-closurefinisher-options:
1723
1724 Options
1725 ^^^^^^^
1726
1727 .. _apireference-finisheroptions-closurefinisher-options-closure:
1728
1729 closure
1730 +++++++
1731
1732 :aspect:`Data type`
1733 \Closure
1734
1735 :aspect:`Mandatory`
1736 Yes
1737
1738 :aspect:`Default value`
1739 null
1740
1741
1742 .. _apireference-finisheroptions-confirmationfinisher:
1743
1744 Confirmation finisher
1745 ---------------------
1746
1747 A simple finisher that outputs a given text.
1748
1749 Usage within form definition
1750
1751 .. code-block:: yaml
1752
1753 identifier: example-form
1754 label: 'example'
1755 type: Form
1756
1757 finishers:
1758 -
1759 identifier: Confirmation
1760 options:
1761 message: 'Thx for using TYPO3'
1762 ...
1763
1764
1765 Usage through code::
1766
1767 $formDefinition->createFinisher('Confirmation', [
1768 'message' => 'foo',
1769 ]);
1770
1771 or create manually (not preferred)::
1772
1773 $confirmationFinisher = $this->objectManager->get(ConfirmationFinisher::class);
1774 $confirmationFinisher->setOptions([
1775 'message' => 'foo',
1776 ]);
1777 $formDefinition->addFinisher($confirmationFinisher);
1778
1779
1780 .. _apireference-finisheroptions-confirmationfinisher-options:
1781
1782 Options
1783 ^^^^^^^
1784
1785 .. _apireference-finisheroptions-confirmationfinisher-options-message:
1786
1787 message
1788 +++++++
1789
1790 :aspect:`Data type`
1791 string
1792
1793 :aspect:`Mandatory`
1794 Yes
1795
1796 :aspect:`Default value`
1797 The form has been submitted.
1798
1799
1800 .. _apireference-finisheroptions-deleteuploadsfinisher:
1801
1802 DeleteUploads finisher
1803 ----------------------
1804
1805 This finisher remove the currently submited files.
1806 Use this finisher e.g after the email finisher if you don't want to keep the files online.
1807
1808
1809 Usage within form definition
1810
1811 .. code-block:: yaml
1812
1813 identifier: example-form
1814 label: 'example'
1815 type: Form
1816
1817 finishers:
1818 -
1819 identifier: DeleteUploads
1820 ...
1821
1822
1823 Usage through code::
1824
1825 $formDefinition->createFinisher('DeleteUploads');
1826
1827 or create manually (not preferred)::
1828
1829 $deleteUploadsFinisher = $this->objectManager->get(DeleteUploadsFinisher::class);
1830 $formDefinition->addFinisher($deleteUploadsFinisher);
1831
1832
1833 .. _apireference-finisheroptions-emailfinisher:
1834
1835 Email finisher
1836 --------------
1837
1838 This finisher sends an email to one recipient.
1839 EXT:form uses 2 EmailFinisher declarations with the identifiers ``EmailToReceiver`` and ``EmailToSender``.
1840
1841 Usage within form definition
1842
1843 .. code-block:: yaml
1844
1845 identifier: example-form
1846 label: 'example'
1847 type: Form
1848
1849 finishers:
1850 -
1851 identifier: EmailToReceiver
1852 options:
1853 subject: 'Your message'
1854 recipientAddress: your.company@example.com
1855 recipientName: 'Your Company name'
1856 senderAddress: 'form@example.com'
1857 senderName: 'form submitter'
1858 ...
1859
1860
1861 Usage through code::
1862
1863 $formDefinition->createFinisher('EmailToReceiver', [
1864 'subject' => 'Your message',
1865 'recipientAddress' => 'your.company@example.com',
1866 'recipientName' => 'Your Company name',
1867 'senderAddress' => 'form@example.com',
1868 'senderName' => 'form submitter',
1869 ]);
1870
1871 or create manually (not preferred)::
1872
1873 $emailFinisher = $this->objectManager->get(EmailFinisher::class);
1874 $emailFinisher->setOptions([
1875 'subject' => 'Your message',
1876 'recipientAddress' => 'your.company@example.com',
1877 'recipientName' => 'Your Company name',
1878 'senderAddress' => 'form@example.com',
1879 'senderName' => 'form submitter',
1880 ]);
1881 $formDefinition->addFinisher($emailFinisher);
1882
1883
1884 .. _apireference-finisheroptions-emailfinisher-options:
1885
1886 Options
1887 ^^^^^^^
1888
1889 .. _apireference-finisheroptions-emailfinisher-options-subject:
1890
1891 subject
1892 +++++++
1893
1894 :aspect:`Data type`
1895 string
1896
1897 :aspect:`Mandatory`
1898 Yes
1899
1900 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
1901 undefined
1902
1903 :aspect:`Description`
1904 Subject of the email
1905
1906
1907 .. _apireference-finisheroptions-emailfinisher-options-recipientaddress:
1908
1909 recipientAddress
1910 ++++++++++++++++
1911
1912 :aspect:`Data type`
1913 string
1914
1915 :aspect:`Mandatory`
1916 Yes
1917
1918 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
1919 undefined
1920
1921 :aspect:`Description`
1922 Email address of the recipient (To)
1923
1924
1925 .. _apireference-finisheroptions-emailfinisher-options-recipientname:
1926
1927 recipientName
1928 +++++++++++++
1929
1930 :aspect:`Data type`
1931 string
1932
1933 :aspect:`Mandatory`
1934 No
1935
1936 :aspect:`Default value`
1937 empty string
1938
1939 :aspect:`Description`
1940 Human-readable name of the recipient
1941
1942
1943 .. _apireference-finisheroptions-emailfinisher-options-senderaddress:
1944
1945 senderAddress
1946 +++++++++++++
1947
1948 :aspect:`Data type`
1949 string
1950
1951 :aspect:`Mandatory`
1952 Yes
1953
1954 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
1955 undefined
1956
1957 :aspect:`Description`
1958 Email address of the sender/ visitor (From)
1959
1960
1961 .. _apireference-finisheroptions-emailfinisher-options-sendername:
1962
1963 senderName
1964 ++++++++++
1965
1966 :aspect:`Data type`
1967 string
1968
1969 :aspect:`Mandatory`
1970 No
1971
1972 :aspect:`Default value`
1973 empty string
1974
1975 :aspect:`Description`
1976 Human-readable name of the sender
1977
1978
1979 .. _apireference-finisheroptions-emailfinisher-options-replytoaddress:
1980
1981 replyToAddress
1982 ++++++++++++++
1983
1984 :aspect:`Data type`
1985 string/ array
1986
1987 :aspect:`Mandatory`
1988 No
1989
1990 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
1991 undefined
1992
1993 :aspect:`Description`
1994 Email address of to be used as reply-to email (use multiple addresses with an array)
1995
1996 .. note::
1997
1998 For the moment, the ``form editor`` cannot deal with multiple reply-to addresses (use multiple addresses with an array)
1999
2000
2001 .. _apireference-finisheroptions-emailfinisher-options-carboncopyaddress:
2002
2003 carbonCopyAddress
2004 +++++++++++++++++
2005
2006 :aspect:`Data type`
2007 string/ array
2008
2009 :aspect:`Mandatory`
2010 No
2011
2012 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
2013 undefined
2014
2015 :aspect:`Description`
2016 Email address of the copy recipient (use multiple addresses with an array)
2017
2018 .. note::
2019
2020 For the moment, the ``form editor`` cannot deal with multiple copy recipient addresses (use multiple addresses with an array)
2021
2022
2023 .. _apireference-finisheroptions-emailfinisher-options-blindcarboncopyaddress:
2024
2025 blindCarbonCopyAddress
2026 ++++++++++++++++++++++
2027
2028 :aspect:`Data type`
2029 string/ array
2030
2031 :aspect:`Mandatory`
2032 No
2033
2034 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
2035 undefined
2036
2037 :aspect:`Description`
2038 Email address of the blind copy recipient (use multiple addresses with an array)
2039
2040 .. note::
2041
2042 For the moment, the ``form editor`` cannot deal with multiple blind copy recipient addresses (use multiple addresses with an array)
2043
2044
2045 .. _apireference-finisheroptions-emailfinisher-options-format:
2046
2047 format
2048 ++++++
2049
2050 :aspect:`Data type`
2051 string
2052
2053 :aspect:`Mandatory`
2054 No
2055
2056 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
2057 html
2058
2059 :aspect:`possible values`
2060 html/ plaintext
2061
2062 :aspect:`Description`
2063 The format of the email. By default mails are sent as HTML.
2064
2065
2066 .. _apireference-finisheroptions-emailfinisher-options-attachuploads:
2067
2068 attachUploads
2069 +++++++++++++
2070
2071 :aspect:`Data type`
2072 bool
2073
2074 :aspect:`Mandatory`
2075 No
2076
2077 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
2078 true
2079
2080 :aspect:`Description`
2081 If set, all uploaded items are attached to the email.
2082
2083
2084 .. _apireference-finisheroptions-emailfinisher-options-translation-translationfiles:
2085
2086 translation.translationFiles
2087 ++++++++++++++++++++++++++++
2088
2089 :aspect:`Data type`
2090 string/ array
2091
2092 :aspect:`Mandatory`
2093 No
2094
2095 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
2096 undefined
2097
2098 :aspect:`Description`
2099 If set, this translation file(s) will be used for finisher option translations.
2100 If not set, the translation file(s) from the 'Form' element will be used.
2101 Read :ref:`Translate finisher options<concepts-frontendrendering-translation-finishers>` for more informations.
2102
2103
2104 .. _apireference-finisheroptions-emailfinisher-options-translation-language:
2105
2106 translation.language
2107 ++++++++++++++++++++
2108
2109 :aspect:`Data type`
2110 string
2111
2112 :aspect:`Mandatory`
2113 No
2114
2115 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
2116 undefined
2117
2118 :aspect:`Description`
2119 If not set, the finisher options are translated depending on the current frontend language (if translations exists).
2120 This option allows you to force translations for a given sys_language isocode, e.g 'dk' or 'de'.
2121 Read :ref:`Translate finisher options<concepts-frontendrendering-translation-finishers>` for more informations.
2122
2123
2124 .. _apireference-finisheroptions-emailfinisher-options-templatepathandfilename:
2125
2126 templatePathAndFilename
2127 +++++++++++++++++++++++
2128
2129 :aspect:`Data type`
2130 string
2131
2132 :aspect:`Mandatory`
2133 Yes
2134
2135 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
2136 'EXT:form/Resources/Private/Frontend/Templates/Finishers/Email/{@format}.html'
2137
2138 :aspect:`Description`
2139 Template path and filename for the mail body.
2140 The placeholder {\@format} will be replaced with the value from option ``format``
2141
2142
2143 .. _apireference-finisheroptions-emailfinisher-options-layoutrootpaths:
2144
2145 layoutRootPaths
2146 +++++++++++++++
2147
2148 :aspect:`Data type`
2149 array
2150
2151 :aspect:`Mandatory`
2152 No
2153
2154 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
2155 undefined
2156
2157 :aspect:`Description`
2158 Fluid layout paths
2159
2160
2161 .. _apireference-finisheroptions-emailfinisher-options-partialrootpaths:
2162
2163 partialRootPaths
2164 ++++++++++++++++
2165
2166 :aspect:`Data type`
2167 array
2168
2169 :aspect:`Mandatory`
2170 No
2171
2172 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
2173 undefined
2174
2175 :aspect:`Description`
2176 Fluid partial paths
2177
2178
2179 .. _apireference-finisheroptions-emailfinisher-options-variables:
2180
2181 variables
2182 +++++++++
2183
2184 :aspect:`Data type`
2185 array
2186
2187 :aspect:`Mandatory`
2188 No
2189
2190 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
2191 undefined
2192
2193 :aspect:`Description`
2194 associative array of variables which are available inside the Fluid template
2195
2196
2197 .. _apireference-finisheroptions-flashmessagefinisher:
2198
2199 FlashMessage finisher
2200 ---------------------
2201
2202 A simple finisher that adds a message to the FlashMessageContainer.
2203
2204 Usage within form definition
2205
2206 .. code-block:: yaml
2207
2208 identifier: example-form
2209 label: 'example'
2210 type: Form
2211
2212 finishers:
2213 -
2214 identifier: FlashMessage
2215 options:
2216 messageTitle: 'Merci'
2217 messageCode: 201905041245
2218 messageBody: 'Thx for using %s'
2219 messageArguments:
2220 - 'TYPO3'
2221 severity: 0
2222 ...
2223
2224
2225 Usage through code::
2226
2227 $formDefinition->createFinisher('FlashMessage', [
2228 'messageTitle' => 'Merci',
2229 'messageCode' => 201905041245,
2230 'messageBody' => 'Thx for using %s',
2231 'messageArguments' => ['TYPO3'],
2232 'severity' => \TYPO3\CMS\Core\Messaging\AbstractMessage::OK,
2233 ]);
2234
2235 or create manually (not preferred)::
2236
2237 $flashMessageFinisher = $this->objectManager->get(FlashMessageFinisher::class);
2238 $flashMessageFinisher->setOptions([
2239 'messageTitle' => 'Merci',
2240 'messageCode' => 201905041245,
2241 'messageBody' => 'Thx for using %s',
2242 'messageArguments' => ['TYPO3'],
2243 'severity' => \TYPO3\CMS\Core\Messaging\AbstractMessage::OK,
2244 ]);
2245 $formDefinition->addFinisher($flashMessageFinisher);
2246
2247
2248 .. _apireference-finisheroptions-flashmessagefinisher-options:
2249
2250 Options
2251 ^^^^^^^
2252
2253 .. _apireference-finisheroptions-flashmessagefinisher-options-messagebody:
2254
2255 messageBody
2256 +++++++++++
2257
2258 :aspect:`Data type`
2259 string
2260
2261 :aspect:`Mandatory`
2262 Yes
2263
2264 :aspect:`Description`
2265 The flash message body
2266
2267
2268 .. _apireference-finisheroptions-flashmessagefinisher-options-messagetitle:
2269
2270 messageTitle
2271 ++++++++++++
2272
2273 :aspect:`Data type`
2274 string
2275
2276 :aspect:`Mandatory`
2277 No
2278
2279 :aspect:`Default value`
2280 empty string
2281
2282 :aspect:`Description`
2283 The flash message title, if needed
2284
2285
2286 .. _apireference-finisheroptions-flashmessagefinisher-options-messagearguments:
2287
2288 messageArguments
2289 ++++++++++++++++
2290
2291 :aspect:`Data type`
2292 array
2293
2294 :aspect:`Mandatory`
2295 No
2296
2297 :aspect:`Default value`
2298 empty array
2299
2300 :aspect:`Description`
2301 The flash message arguments, if needed
2302
2303
2304 .. _apireference-finisheroptions-flashmessagefinisher-options-messagecode:
2305
2306 messageCode
2307 +++++++++++
2308
2309 :aspect:`Data type`
2310 int
2311
2312 :aspect:`Mandatory`
2313 Yes
2314
2315 :aspect:`Description`
2316 The flash message code
2317
2318
2319 .. _apireference-finisheroptions-flashmessagefinisher-options-severity:
2320
2321 severity
2322 ++++++++
2323
2324 :aspect:`Data type`
2325 int
2326
2327 :aspect:`Mandatory`
2328 No
2329
2330 :aspect:`Default value`
2331 \TYPO3\CMS\Core\Messaging\AbstractMessage::OK (0)
2332
2333 :aspect:`Description`
2334 The flash message severity code.
2335 See \TYPO3\CMS\Core\Messaging\AbstractMessage constants for the codes.
2336
2337
2338 .. _apireference-finisheroptions-redirectfinisher:
2339
2340 Redirect finisher
2341 -----------------
2342
2343 A simple finisher that redirects to another page.
2344
2345 Usage within form definition
2346
2347 .. code-block:: yaml
2348
2349 identifier: example-form
2350 label: 'example'
2351 type: Form
2352
2353 finishers:
2354 -
2355 identifier: Redirect
2356 options:
2357 pageUid: 1
2358 additionalParameters: 'param1=value1&param2=value2'
2359 ...
2360
2361
2362 Usage through code::
2363
2364 $formDefinition->createFinisher('Redirect', [
2365 'pageUid' => 1,
2366 'additionalParameters' => 'param1=value1&param2=value2',
2367 ]);
2368
2369 or create manually (not preferred)::
2370
2371 $redirectFinisher = $this->objectManager->get(RedirectFinisher::class);
2372 $redirectFinisher->setOptions([
2373 'pageUid' => 1,
2374 'additionalParameters' => 'param1=value1&param2=value2',
2375 ]);
2376 $formDefinition->addFinisher($redirectFinisher);
2377
2378
2379 .. _apireference-finisheroptions-redirectfinisher-options:
2380
2381 Options
2382 ^^^^^^^
2383
2384 .. _apireference-finisheroptions-redirectfinisher-options-pageuid:
2385
2386 pageUid
2387 +++++++
2388
2389 :aspect:`Data type`
2390 int
2391
2392 :aspect:`Mandatory`
2393 Yes
2394
2395 :aspect:`Default value`
2396 1
2397
2398 :aspect:`Description`
2399 Redirect to this page uid
2400
2401
2402 .. _apireference-finisheroptions-redirectfinisher-options-additionalparameters:
2403
2404 additionalParameters
2405 ++++++++++++++++++++
2406
2407 :aspect:`Data type`
2408 string
2409
2410 :aspect:`Mandatory`
2411 No
2412
2413 :aspect:`Default value`
2414 empty string
2415
2416 :aspect:`Description`
2417 Additional parameters which should be used on the target page
2418
2419
2420 .. _apireference-finisheroptions-redirectfinisher-options-delay:
2421
2422 delay
2423 +++++
2424
2425 :aspect:`Data type`
2426 int
2427
2428 :aspect:`Mandatory`
2429 No
2430
2431 :aspect:`Default value`
2432 0
2433
2434 :aspect:`Description`
2435 The redirect delay in seconds.
2436
2437
2438 .. _apireference-finisheroptions-redirectfinisher-options-statuscode:
2439
2440 statusCode
2441 ++++++++++
2442
2443 :aspect:`Data type`
2444 int
2445
2446 :aspect:`Mandatory`
2447 No
2448
2449 :aspect:`Default value`
2450 303
2451
2452 :aspect:`Description`
2453 The HTTP status code for the redirect. Default is "303 See Other".
2454
2455
2456 .. _apireference-finisheroptions-savetodatabasefinisher:
2457
2458 SaveToDatabase finisher
2459 -----------------------
2460
2461 This finisher saves the data from a submitted form into a database table.
2462
2463
2464 Usage within form definition
2465
2466 .. code-block:: yaml
2467
2468 identifier: example-form
2469 label: 'example'
2470 type: Form
2471
2472 finishers:
2473 -
2474 identifier: SaveToDatabase
2475 options:
2476 table: 'fe_users'
2477 mode: update
2478 whereClause:
2479 uid: 1
2480 databaseColumnMappings:
2481 pid:
2482 value: 1
2483 elements:
2484 textfield-identifier-1:
2485 mapOnDatabaseColumn: 'first_name'
2486 textfield-identifier-2:
2487 mapOnDatabaseColumn: 'last_name'
2488 textfield-identifier-3:
2489 mapOnDatabaseColumn: 'username'
2490 advancedpassword-1:
2491 mapOnDatabaseColumn: 'password'
2492 skipIfValueIsEmpty: true
2493 ...
2494
2495
2496 Usage through code::
2497
2498 $formDefinition->createFinisher('SaveToDatabase', [
2499 'table' => 'fe_users',
2500 'mode' => 'update',
2501 'whereClause' => [
2502 'uid' => 1,
2503 ],
2504 'databaseColumnMappings' => [
2505 'pid' => ['value' => 1],
2506 ],
2507 'elements' => [
2508 'textfield-identifier-1' => ['mapOnDatabaseColumn' => 'first_name'],
2509 'textfield-identifier-2' => ['mapOnDatabaseColumn' => 'last_name'],
2510 'textfield-identifier-3' => ['mapOnDatabaseColumn' => 'username'],
2511 'advancedpassword-1' => [
2512 'mapOnDatabaseColumn' => 'password',
2513 'skipIfValueIsEmpty' => true,
2514 ],
2515 ],
2516 ]);
2517
2518 or create manually (not preferred)::
2519
2520 $saveToDatabaseFinisher = $this->objectManager->get(SaveToDatabaseFinisher::class);
2521 $saveToDatabaseFinisher->setOptions([
2522 'table' => 'fe_users',
2523 'mode' => 'update',
2524 'whereClause' => [
2525 'uid' => 1,
2526 ],
2527 'databaseColumnMappings' => [
2528 'pid' => ['value' => 1],
2529 ],
2530 'elements' => [
2531 'textfield-identifier-1' => ['mapOnDatabaseColumn' => 'first_name'],
2532 'textfield-identifier-2' => ['mapOnDatabaseColumn' => 'last_name'],
2533 'textfield-identifier-3' => ['mapOnDatabaseColumn' => 'username'],
2534 'advancedpassword-1' => [
2535 'mapOnDatabaseColumn' => 'password',
2536 'skipIfValueIsEmpty' => true,
2537 ],
2538 ],
2539 ]);
2540 $formDefinition->addFinisher($saveToDatabaseFinisher);
2541
2542 You can write options as an array to perform multiple database operations.
2543
2544 Usage within form definition
2545
2546 .. code-block:: yaml
2547
2548 identifier: example-form
2549 label: 'example'
2550 type: Form
2551
2552 finishers:
2553 -
2554 identifier: SaveToDatabase
2555 options:
2556 1:
2557 table: 'my_table'
2558 mode: insert
2559 databaseColumnMappings:
2560 some_column:
2561 value: 'cool'
2562 2:
2563 table: 'my_other_table'
2564 mode: update
2565 whereClause:
2566 pid: 1
2567 databaseColumnMappings:
2568 some_other_column:
2569 value: '{SaveToDatabase.insertedUids.1}'
2570 ...
2571
2572
2573 Usage through code::
2574
2575 $formDefinition->createFinisher('SaveToDatabase', [
2576 1 => [
2577 'table' => 'my_table',
2578 'mode' => 'insert',
2579 'databaseColumnMappings' => [
2580 'some_column' => ['value' => 'cool'],
2581 ],
2582 ],
2583 2 => [
2584 'table' => 'my_other_table',
2585 'mode' => 'update',
2586 'whereClause' => [
2587 'pid' => 1,
2588 ],
2589 'databaseColumnMappings' => [
2590 'some_other_column' => ['value' => '{SaveToDatabase.insertedUids.1}'],
2591 ],
2592 ],
2593 ]);
2594
2595 or create manually (not preferred)::
2596
2597 $saveToDatabaseFinisher = $this->objectManager->get(SaveToDatabaseFinisher::class);
2598 $saveToDatabaseFinisher->setOptions([
2599 1 => [
2600 'table' => 'my_table',
2601 'mode' => 'insert',
2602 'databaseColumnMappings' => [
2603 'some_column' => ['value' => 'cool'],
2604 ],
2605 ],
2606 2 => [
2607 'table' => 'my_other_table',
2608 'mode' => 'update',
2609 'whereClause' => [
2610 'pid' => 1,
2611 ],
2612 'databaseColumnMappings' => [
2613 'some_other_column' => ['value' => '{SaveToDatabase.insertedUids.1}'],
2614 ],
2615 ],
2616 ]);
2617 $formDefinition->addFinisher($saveToDatabaseFinisher);
2618
2619
2620 This performs 2 database operations.
2621 One insert and one update.
2622 You can access the inserted uids through '{SaveToDatabase.insertedUids.<theArrayKeyNumberWithinOptions>}'
2623 If you perform a insert operation, the value of the inserted database row will be stored within the FinisherVariableProvider.
2624 <theArrayKeyNumberWithinOptions> references to the numeric options.* key.
2625
2626
2627 .. _apireference-finisheroptions-savetodatabasefinisher-options:
2628
2629 Options
2630 ^^^^^^^
2631
2632 .. _apireference-finisheroptions-savetodatabasefinisher-options-table:
2633
2634 table
2635 +++++
2636
2637 :aspect:`Data type`
2638 string
2639
2640 :aspect:`Mandatory`
2641 Yes
2642
2643 :aspect:`Default value`
2644 null
2645
2646 :aspect:`Description`
2647 Insert or update values into this table.
2648
2649
2650 .. _apireference-finisheroptions-savetodatabasefinisher-options-mode:
2651
2652 mode
2653 ++++
2654
2655 :aspect:`Data type`
2656 string
2657
2658 :aspect:`Mandatory`
2659 No
2660
2661 :aspect:`Default value`
2662 'insert'
2663
2664 :aspect:`Possible values`
2665 insert/ update
2666
2667 :aspect:`Description`
2668 ``insert`` will create a new database row with the values from the submitted form and/or some predefined values. @see options.elements and options.databaseFieldMappings
2669
2670 ``update`` will update a given database row with the values from the submitted form and/or some predefined values. 'options.whereClause' is then required.
2671
2672
2673 .. _apireference-finisheroptions-savetodatabasefinisher-options-whereclause:
2674
2675 whereClause
2676 +++++++++++
2677
2678 :aspect:`Data type`
2679 array
2680
2681 :aspect:`Mandatory`
2682 Yes, if mode = update
2683
2684 :aspect:`Default value`
2685 empty array
2686
2687 :aspect:`Description`
2688 This where clause will be used for a database update action
2689
2690
2691 .. _apireference-finisheroptions-savetodatabasefinisher-options-elements:
2692
2693 elements
2694 ++++++++
2695
2696 :aspect:`Data type`
2697 array
2698
2699 :aspect:`Mandatory`
2700 Yes
2701
2702 :aspect:`Default value`
2703 empty array
2704
2705 :aspect:`Description`
2706 Use ``options.elements`` to map form element values to existing database columns.
2707 Each key within ``options.elements`` has to match with a form element identifier.
2708 The value for each key within ``options.elements`` is an array with additional informations.
2709
2710
2711 .. _apireference-finisheroptions-savetodatabasefinisher-options-elements-<formelementidentifier>-mapondatabasecolumn:
2712
2713 elements.<formElementIdentifier>.mapOnDatabaseColumn
2714 ++++++++++++++++++++++++++++++++++++++++++++++++++++
2715
2716 :aspect:`Data type`
2717 string
2718
2719 :aspect:`Mandatory`
2720 Yes
2721
2722 :aspect:`Default value`
2723 undefined
2724
2725 :aspect:`Description`
2726 The value from the submitted form element with the identifier ``<formElementIdentifier>`` will be written into this database column.
2727
2728
2729 .. _apireference-finisheroptions-savetodatabasefinisher-options-elements-<formelementidentifier>-skipifvalueisempty:
2730
2731 elements.<formElementIdentifier>.skipIfValueIsEmpty
2732 +++++++++++++++++++++++++++++++++++++++++++++++++++
2733
2734 :aspect:`Data type`
2735 bool
2736
2737 :aspect:`Mandatory`
2738 No
2739
2740 :aspect:`Default value`
2741 false
2742
2743 :aspect:`Description`
2744 Set this to true if the database column should not be written if the value from the submitted form element with the identifier
2745 ``<formElementIdentifier>`` is empty (think about password fields etc.). Empty means strings without content, whitespace is valid content.
2746
2747
2748 .. _apireference-finisheroptions-savetodatabasefinisher-options-elements-<formelementidentifier>-savefileidentifierinsteadofuid:
2749
2750 elements.<formElementIdentifier>.saveFileIdentifierInsteadOfUid
2751 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2752
2753 :aspect:`Data type`
2754 bool
2755
2756 :aspect:`Mandatory`
2757 No
2758
2759 :aspect:`Default value`
2760 false
2761
2762 :aspect:`Description`
2763 Set this to true if the database column should not be written if the value from the submitted form element with the identifier
2764 ``<formElementIdentifier>`` is empty (think about password fields etc.).
2765
2766 This setting only rules for form elements which creates a FAL object like ``FileUpload`` or ``ImageUpload``.
2767 By default, the uid of the FAL object will be written into the database column. Set this to true if you want to store the
2768 FAL identifier (1:/user_uploads/some_uploaded_pic.jpg) instead.
2769
2770
2771 .. _apireference-finisheroptions-savetodatabasefinisher-options-elements-<formelementidentifier>-dateformat:
2772
2773 elements.<formElementIdentifier>.dateFormat
2774 +++++++++++++++++++++++++++++++++++++++++++
2775
2776 :aspect:`Data type`
2777 string
2778
2779 :aspect:`Mandatory`
2780 No
2781
2782 :aspect:`Default value`
2783 'U'
2784
2785 :aspect:`Description`
2786 If the internal datatype is :php:`\DateTime` which is true for the form element types
2787 :yaml:`DatePicker` and :yaml:`Date`, the object needs to be converted into a string value.
2788 This option allows you to define the format of the date in case of such a conversion.
2789 You can use every format accepted by the PHP :php:`date()` function (http://php.net/manual/en/function.date.php#refsect1-function.date-parameters).
2790 The default value is "U" which leads to a Unix timestamp.
2791
2792
2793 .. _apireference-finisheroptions-savetodatabasefinisher-options-databasecolumnmappings:
2794
2795 databaseColumnMappings
2796 ++++++++++++++++++++++
2797
2798 :aspect:`Data type`
2799 array
2800
2801 :aspect:`Mandatory`
2802 No
2803
2804 :aspect:`Default value`
2805 empty array
2806
2807 :aspect:`Description`
2808 Use this to map database columns to static values.
2809 Each key within ``options.databaseColumnMappings`` has to match with an existing database column.
2810 The value for each key within ``options.databaseColumnMappings`` is an array with additional informations.
2811
2812 This mapping is done *before* the ``options.element`` mapping.
2813 This means if you map a database column to a value through ``options.databaseColumnMappings`` and map a submitted
2814 form element value to the same database column through ``options.element``, the submitted form element value
2815 will override the value you set within ``options.databaseColumnMappings``.
2816
2817
2818 .. _apireference-finisheroptions-savetodatabasefinisher-options-databasecolumnmappings.<databasecolumnname>.value:
2819
2820 databaseColumnMappings.<databaseColumnName>.value
2821 +++++++++++++++++++++++++++++++++++++++++++++++++
2822
2823 :aspect:`Data type`
2824 string
2825
2826 :aspect:`Mandatory`
2827 Yes
2828
2829 :aspect:`Default value`
2830 undefined
2831
2832 :aspect:`Description`
2833 The value which will be written to the database column.
2834 You can also use the :ref:`FormRuntime accessor feature<concepts-finishers-customfinisherimplementations-accessingoptions-formruntimeaccessor>` to access every getable property from the ``FormRuntime``
2835 In short: use something like ``{<formElementIdentifier>}`` to get the value from the submitted form element with the identifier ``<formElementIdentifier>``.
2836
2837 If you use the FormRuntime accessor feature within ``options.databaseColumnMappings``, the functionality is nearly identical
2838 to the ``options.elements`` configuration variant.
2839
2840
2841 .. _apireference-finisheroptions-savetodatabasefinisher-options-databasecolumnmappings.<databasecolumnname>.skipifvalueisempty:
2842
2843 databaseColumnMappings.<databaseColumnName>.skipIfValueIsEmpty
2844 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2845
2846 :aspect:`Data type`
2847 bool
2848
2849 :aspect:`Mandatory`
2850 No
2851
2852 :aspect:`Default value`
2853 false
2854
2855 :aspect:`Description`
2856 Set this to true if the database column should not be written if the value from ``options.databaseColumnMappings.<databaseColumnName>.value`` is empty.
2857
2858
2859
2860 .. _apireference-formeditor:
2861
2862 Form editor
2863 ===========
2864
2865
2866 .. _apireference-formeditor-hooks:
2867
2868 Hooks
2869 -----
2870
2871 EXT:form implements various hooks so that forms can be manipulated while being
2872 created or saved.
2873
2874
2875 .. _apireference-formeditor-hooks-beforeformcreate:
2876
2877 beforeFormCreate
2878 ^^^^^^^^^^^^^^^^
2879
2880 The form manager calls the 'beforeFormCreate' hook.
2881
2882
2883 .. _apireference-formeditor-hooks-beforeformcreate-connect:
2884
2885 Connect to the hook
2886 +++++++++++++++++++
2887
2888 ::
2889
2890 $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['beforeFormCreate'][<useATimestampAsKeyPlease>]
2891 = \VENDOR\YourNamespace\YourClass::class;
2892
2893
2894 .. note::
2895
2896 Wondering what :ref:`useATimestampAsKeyPlease<useATimestampAsKeyPlease>`
2897 means?
2898
2899
2900 .. _apireference-formeditor-hooks-beforeformcreate-use:
2901
2902 Use the hook
2903 ++++++++++++
2904
2905 ::
2906
2907 /**
2908 * @param string $formPersistenceIdentifier
2909 * @param array $formDefinition
2910 * @return array
2911 */
2912 public function beforeFormCreate(string $formPersistenceIdentifier, array $formDefinition): array
2913 {
2914 return $formDefinition;
2915 }
2916
2917
2918 .. _apireference-formeditor-hooks-beforeformduplicate:
2919
2920 beforeFormDuplicate
2921 ^^^^^^^^^^^^^^^^^^^
2922
2923 The form manager call the 'beforeFormDuplicate' hook.
2924
2925
2926 .. _apireference-formeditor-hooks-beforeformduplicate-connect:
2927
2928 Connect to the hook
2929 +++++++++++++++++++
2930
2931 ::
2932
2933 $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['beforeFormDuplicate'][<useATimestampAsKeyPlease>]
2934 = \VENDOR\YourNamespace\YourClass::class;
2935
2936
2937 .. note::
2938
2939 Wondering what :ref:`useATimestampAsKeyPlease<useATimestampAsKeyPlease>`
2940 means?
2941
2942
2943 .. _apireference-formeditor-hooks-beforeformduplicate-use:
2944
2945 Use the hook
2946 ++++++++++++
2947
2948 ::
2949
2950 /**
2951 * @param string $formPersistenceIdentifier
2952 * @param array $formDefinition
2953 * @return array
2954 */
2955 public function beforeFormDuplicate(string $formPersistenceIdentifier, array $formDefinition): array
2956 {
2957 return $formDefinition;
2958 }
2959
2960
2961 .. _apireference-formeditor-hooks-beforeformdelete:
2962
2963 beforeFormDelete
2964 ^^^^^^^^^^^^^^^^
2965
2966 The form manager call the 'beforeFormDelete' hook.
2967
2968
2969 .. _apireference-formeditor-hooks-beforeformdelete-connect:
2970
2971 Connect to the hook
2972 +++++++++++++++++++
2973
2974 ::
2975
2976 $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['beforeFormDelete'][<useATimestampAsKeyPlease>]
2977 = \VENDOR\YourNamespace\YourClass::class;
2978
2979
2980 .. note::
2981
2982 Wondering what :ref:`useATimestampAsKeyPlease<useATimestampAsKeyPlease>`
2983 means?
2984
2985
2986 .. _apireference-formeditor-hooks-beforeformdelete-use:
2987
2988 Use the hook
2989 ++++++++++++
2990
2991 ::
2992
2993 /**
2994 * @param string $formPersistenceIdentifier
2995 * @return void
2996 */
2997 public function beforeFormDelete(string $formPersistenceIdentifier)
2998 {
2999 }
3000
3001
3002 .. _apireference-formeditor-hooks-beforeformsave:
3003
3004 beforeFormSave
3005 ^^^^^^^^^^^^^^
3006
3007 The form editor call the 'beforeFormSave' hook.
3008
3009
3010 .. _apireference-formeditor-hooks-beforeformsave-connect:
3011
3012 Connect to the hook
3013 +++++++++++++++++++
3014
3015 ::
3016
3017 $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['beforeFormSave'][<useATimestampAsKeyPlease>]
3018 = \VENDOR\YourNamespace\YourClass::class;
3019
3020
3021 .. note::
3022
3023 Wondering what :ref:`useATimestampAsKeyPlease<useATimestampAsKeyPlease>`
3024 means?
3025
3026
3027 .. _apireference-formeditor-hooks-beforeformsave-use:
3028
3029 Use the hook
3030 ++++++++++++
3031
3032 ::
3033
3034 /**
3035 * @param string $formPersistenceIdentifier
3036 * @param array $formDefinition
3037 * @return array
3038 */
3039 public function beforeFormSave(string $formPersistenceIdentifier, array $formDefinition): array
3040 {
3041 return $formDefinition;
3042 }
3043
3044
3045
3046 .. _apireference-formeditor-stage:
3047
3048 Stage
3049 -----
3050
3051
3052 .. _apireference-formeditor-stage-commonabstractformelementtemplates:
3053
3054 Common abstract view form element templates
3055 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3056
3057 The basic idea of the ``abstract view`` is to give a quick overview of the
3058 configuration of form elements, without having to click them in order to view
3059 the detailed configuration in the ``Inspector``. The ``form editor`` requires
3060 for each form element an inline HTML template and the corresponding JavaScript
3061 code. Information matching inline HTML templates to the appropriate form
3062 elements must be configured within :ref:`TYPO3.CMS.Form.prototypes.\<prototypeIdentifier>.formeditor.formEditorPartials <typo3.cms.form.prototypes.\<prototypeidentifier>.formeditor.formeditorpartials>`.
3063 At this point, the key identifying the form element follows a convention:
3064 ``FormElement-<formElementTypeIdentifier>``. The value for the key tells the
3065 ``form editor`` which inline HTML template should be loaded for the respective
3066 form element. This template is then cloned via JavaScript, brought to life
3067 using the form element configuration and shown in the ``Stage`` component.
3068
3069 You can read about how particular form elements are mapped to inline HTML
3070 templates and how the corresponding JavaScript code are executed :ref:`here <apireference-formeditor-basicjavascriptconcepts-events-view-stage-abstract-render-template-perform>`.
3071
3072 The form element inline HTML templates and the corresponding JavaScript code
3073 are configured for reuse. In this way, most form elements you create should be
3074 able to access the components delivered in EXT:form, without requiring separate
3075 implementations (at least we hope so). For your own implementations, study
3076 EXT:form stage templates, which is found under ``Resources/Private/Backend/Partials/FormEditor/Stage/*``.
3077 The corresponding JavaScript code is found under ``Resources/Public/JavaScript/Backend/FormEditor/StageComponent.js``.
3078 The method ``_renderTemplateDispatcher()`` shows, which methods will be used to
3079 render the respective form elements.
3080
3081 Essentially, two different inline HTML templates exists that can be rendered
3082 with two different JavaScript methods, which are described below. The other
3083 inline HTML templates are almost all versions of these two basic variants and
3084 show extra/ other form-element information. The same applies to the
3085 corresponding JavaScript codes.
3086
3087
3088 .. _apireference-formeditor-stage-commonabstractformelementtemplates-simpletemplate:
3089
3090 Stage/SimpleTemplate
3091 ++++++++++++++++++++
3092
3093 This template displays the ``label`` property of the form element. Depending on
3094 the JavaScript rendering method used, a validator icon will be shown on the
3095 right as soon as a validator is added to the form element. In this case, the
3096 used validator labels are likewise displayed, if the form element is selected
3097 and/ or the cursor hovers over the form element. This template should generally
3098 be enough for all possible, self-defined form elements.
3099
3100 The ``Stage/SimpleTemplate`` can then :ref:`be rendered <apireference-formeditor-basicjavascriptconcepts-events-view-stage-abstract-render-template-perform>`
3101 with the method ``getFormEditorApp().getViewModel().getStage().renderSimpleTemplateWithValidators()``.
3102
3103
3104 .. _apireference-formeditor-stage-commonabstractformelementtemplates-selecttemplate:
3105
3106 Stage/SelectTemplate
3107 ++++++++++++++++++++
3108
3109 This template behaves like the ``Stage/SimpleTemplate`` except that it also
3110 shows the chosen options labels of the form elements. This is naturally only
3111 possible for form elements that have ``properties.options.*`` values, e.g.
3112 ``MultiCheckbox``:
3113
3114 .. code-block:: yaml
3115
3116 type: MultiCheckbox
3117 identifier: multicheckbox-1
3118 label: 'Multi checkbox'
3119 properties:
3120 options:
3121 value1: label1
3122 value2: label2
3123
3124 The template will now list 'label1' and 'label2'.
3125
3126 You can copy this template variant for your own form element, if that form-
3127 element template also lists array values, which, however, are not found under
3128 ``properties.options.*``. For this purpose, the 'Stage/FileUploadTemplate' is
3129 an example. It is basically the 'Stage/SelectTemplate' template, with one
3130 altered property.
3131
3132 In the ``FileUpload`` form element, multiple property values are available
3133 under ``properties.allowedMimeTypes.*`` as an array.
3134
3135 .. code-block:: yaml
3136
3137 type: FileUpload
3138 identifier: fileupload-1
3139 label: 'File upload'
3140 properties:
3141 saveToFileMount: '1:/user_upload/'
3142 allowedMimeTypes:
3143 - application/msexcel
3144 - application/pdf
3145
3146 Stage/SelectTemplate
3147
3148 .. code-block:: html
3149
3150 <div data-identifier="multiValueContainer" data-template-property="properties.options">
3151
3152 Stage/FileUploadTemplate
3153
3154 .. code-block:: html
3155
3156 <div data-identifier="multiValueContainer" data-template-property="properties.allowedMimeTypes">
3157
3158 ``data-template-property`` contains the path to the property, which is to be
3159 read out of the form element and then shown in the template.
3160
3161 The ``Stage/SelectTemplate`` can then :ref:`be rendered <apireference-formeditor-basicjavascriptconcepts-events-view-stage-abstract-render-template-perform>`
3162 with the method ``getFormEditorApp().getViewModel().getStage().renderSelectTemplates()``.
3163
3164
3165 .. _apireference-formeditor-basicjavascriptconcepts:
3166
3167 Basic JavaScript Concepts
3168 -------------------------
3169
3170
3171 .. _apireference-formeditor-basicjavascriptconcepts-events:
3172
3173 Events
3174 ^^^^^^
3175
3176 EXT:form implements the ``publish/subscribe pattern`` to put the event handling
3177 into effect. To learn more about this pattern, you should read
3178 https://addyosmani.com/resources/essentialjsdesignpatterns/book/.
3179 Note that the order of the subscriber is not manipulable and that information
3180 flow between the subscribers does not exist. All events must be asynchronously
3181 designed.
3182
3183 Publish an event:
3184
3185 .. code-block:: javascript
3186
3187 getPublisherSubscriber().publish('eventname', [argumentToPublish1, argumentToPublish2, ...]);
3188
3189 Subscribe to an event:
3190
3191 .. code-block:: javascript
3192
3193 var subscriberToken = getPublisherSubscriber().subscribe('eventname', function(topic, args) {
3194 // args[0] = argumentToPublish1
3195 // args[1] = argumentToPublish2
3196 // ...
3197 });
3198
3199 Unsubscribe an event subscriber:
3200
3201 .. code-block:: javascript
3202
3203 getPublisherSubscriber().unsubscribe(subscriberToken);
3204
3205 EXT:form itself publishes and subscribes to the following events:
3206
3207
3208 .. _apireference-formeditor-basicjavascriptconcepts-events-ajax-beforesend:
3209
3210 ajax/beforeSend
3211 +++++++++++++++
3212
3213 Each Ajax request is called before this event is sent. EXT:form uses this event
3214 to display the spinner icon on the save button.
3215
3216 Subscribe to the event:
3217
3218 .. code-block:: javascript
3219
3220 /**
3221 * @private
3222 *
3223 * @param string
3224 * @param array
3225 * @return void
3226 */
3227 getPublisherSubscriber().subscribe('ajax/beforeSend', function(topic, args) {
3228 });
3229
3230
3231 .. _apireference-formeditor-basicjavascriptconcepts-events-ajax-complete:
3232
3233 ajax/complete
3234 +++++++++++++
3235
3236 Each Ajax request is called after the end of this event. EXT:form uses this
3237 event to remove the spinner icon on the save button.
3238
3239 Subscribe to the event:
3240
3241 .. code-block:: javascript
3242
3243 /**
3244 * @private
3245 *
3246 * @param string
3247 * @param array
3248 * @return void
3249 */
3250 getPublisherSubscriber().subscribe('ajax/complete', function(topic, args) {
3251 });
3252
3253
3254 .. _apireference-formeditor-basicjavascriptconcepts-events-core-ajax-error:
3255
3256 core/ajax/error
3257 +++++++++++++++
3258
3259 This event is called if the Ajax request, which is used to save the form or to
3260 render the current page of the form in the ``preview view``, fails. EXT:form
3261 uses this event to show an error message as a flash message and to show the
3262 received error text in the ``preview view``.
3263
3264 Subscribe to the event:
3265
3266 .. code-block:: javascript
3267
3268 /**
3269 * @private
3270 *
3271 * @param string
3272 * @param array
3273 * args[0] = jqXHR
3274 * args[1] = textStatus
3275 * args[2] = errorThrown
3276 * @return void
3277 */
3278 getPublisherSubscriber().subscribe('core/ajax/error', function(topic, args) {
3279 });
3280
3281
3282 .. _apireference-formeditor-basicjavascriptconcepts-events-core-ajax-renderformdefinitionpage-success:
3283
3284 core/ajax/renderFormDefinitionPage/success
3285 ++++++++++++++++++++++++++++++++++++++++++
3286
3287 This event is called if the Ajax request that is used to render the current
3288 page of the form in the ``preview view`` was successful. EXT:form uses this
3289 event to display the rendered form in the ``preview view``.
3290
3291 Subscribe to the event:
3292
3293 .. code-block:: javascript
3294
3295 /**
3296 * @private
3297 *
3298 * @param string
3299 * @param array
3300 * args[0] = html
3301 * args[1] = pageIndex
3302 * @return void
3303 */
3304 getPublisherSubscriber().subscribe('core/ajax/renderFormDefinitionPage/success', function(topic, args) {
3305 });
3306
3307
3308 .. _apireference-formeditor-basicjavascriptconcepts-events-core-ajax-saveformdefinition-success:
3309
3310 core/ajax/saveFormDefinition/success
3311 ++++++++++++++++++++++++++++++++++++
3312
3313 This event is called if the Ajax request that is used to save the form was
3314 successful. EXT:form uses this event to display a success message as a flash
3315 message. The ``form editor`` is also informed that no unsaved content currently
3316 exists.
3317
3318 Subscribe to the event:
3319
3320 .. code-block:: javascript
3321
3322 /**
3323 * @private
3324 *
3325 * @param string
3326 * @param array
3327 * args[0] = html
3328 * @return void
3329 */
3330 getPublisherSubscriber().subscribe('core/ajax/saveFormDefinition/success', function(topic, args) {
3331 });
3332
3333
3334 .. _apireference-formeditor-basicjavascriptconcepts-events-core-applicationstate-add:
3335
3336 core/applicationState/add
3337 +++++++++++++++++++++++++
3338
3339 The addition/ deletion and movement of form elements und property collection
3340 elements (validators/ finishers) is saved in an internal stack so that the
3341 undo/ redo function can be implemented. This event is called whenever the
3342 current state is added to the stack. EXT:form uses this event to reset the
3343 enabled/ disabled state of the undo/ redo buttons.
3344
3345 Subscribe to the event:
3346
3347 .. code-block:: javascript
3348
3349 /**
3350 * @private
3351 *
3352 * @param string
3353 * @param array
3354 * args[0] = applicationState
3355 * args[1] = stackPointer
3356 * args[2] = stackSize
3357 * @return void
3358 */
3359 getPublisherSubscriber().subscribe('core/applicationState/add', function(topic, args) {
3360 });
3361
3362
3363 .. _apireference-formeditor-basicjavascriptconcepts-events-core-currentlyselectedformelementchanged:
3364
3365 core/currentlySelectedFormElementChanged
3366 ++++++++++++++++++++++++++++++++++++++++
3367
3368 The method ``getFormEditorApp().setCurrentlySelectedFormElement()`` tells the
3369 ``form editor`` which form element should currently be dealt with. This method
3370 calls this event at the end.
3371
3372 Subscribe to the event:
3373
3374 .. code-block:: javascript
3375
3376 /**
3377 * @private
3378 *
3379 * @param string
3380 * @param array
3381 * args[0] = formElement
3382 * @return void
3383 */
3384 getPublisherSubscriber().subscribe('core/currentlySelectedFormElementChanged', function(topic, args) {
3385 });
3386
3387
3388 .. _apireference-formeditor-basicjavascriptconcepts-events-core-formelement-somepropertychanged:
3389
3390 core/formElement/somePropertyChanged
3391 ++++++++++++++++++++++++++++++++++++
3392
3393 Each :ref:`FormElement model<apireference-formeditor-basicjavascriptconcepts-formelementmodel>`
3394 can write properties into the ``FormElement model`` through the methods ``get``
3395 and ``set``. Each property path can register an event name for the publisher
3396 through the method ``on``. This event is then always called when a property
3397 path is written via ``set``. Read :ref:`FormElement model<concepts-formeditor-basicjavascriptconcepts-formelementmodel>`
3398 for more information. EXT:form automatically registers for all known property
3399 paths of a form element the event ``core/formElement/somePropertyChanged``.
3400 This means that every property written via ``set`` calls this event. Among
3401 other things, EXT:form uses this event for, for example, updating the label of
3402 a form element in other components (e.g. ``Tree`` component ) when this label
3403 is changed. Furthermore, any validation errors from form element properties
3404 are indicated by this event in the ``Tree`` component.
3405
3406 Subscribe to the event:
3407
3408 .. code-block:: javascript
3409
3410 /**
3411 * @private
3412 *
3413 * @param string
3414 * @param array
3415 * args[0] = propertyPath
3416 * args[1] = value
3417 * args[2] = oldValue
3418 * args[3] = formElementIdentifierPath
3419 * @return void
3420 */
3421 getPublisherSubscriber().subscribe('core/formElement/somePropertyChanged', function(topic, args) {
3422 });
3423
3424
3425 .. _apireference-formeditor-basicjavascriptconcepts-events-view-collectionelement-moved:
3426
3427 view/collectionElement/moved
3428 ++++++++++++++++++++++++++++
3429
3430 The method ``getFormEditorApp().getViewModel().movePropertyCollectionElement()``
3431 calls this event at the end. EXT:form uses this event to re-render the
3432 ``Inspector`` component as soon as a property collection element (validator/
3433 finisher) is moved.
3434
3435 Subscribe to the event:
3436
3437 .. code-block:: javascript
3438
3439 /**
3440 * @private
3441 *
3442 * @param string
3443 * @param array
3444 * args[0] = movedCollectionElementIdentifier
3445 * args[1] = previousCollectionElementIdentifier
3446 * args[2] = nextCollectionElementIdentifier
3447 * args[3] = collectionName
3448 * @return void
3449 */
3450 getPublisherSubscriber().subscribe('view/collectionElement/moved', function(topic, args) {
3451 });
3452
3453
3454 .. _apireference-formeditor-basicjavascriptconcepts-events-view-collectionelement-new-added:
3455
3456 view/collectionElement/new/added
3457 ++++++++++++++++++++++++++++++++
3458
3459 The method ``getFormEditorApp().getViewModel().createAndAddPropertyCollectionElement()``
3460 calls this event at the end. EXT:form uses this event to re-render the
3461 ``Inspector`` component as soon as a property collection element (validator/
3462 finisher) is created and added.
3463
3464 Subscribe to the event:
3465
3466 .. code-block:: javascript
3467
3468 /**
3469 * @private
3470 *
3471 * @param string
3472 * @param array
3473 * args[0] = collectionElementIdentifier
3474 * args[1] = collectionName
3475 * args[2] = formElement
3476 * args[3] = collectionElementConfiguration
3477 * args[4] = referenceCollectionElementIdentifier
3478 * @return void
3479 */
3480 getPublisherSubscriber().subscribe('view/collectionElement/new/added', function(topic, args) {
3481 });
3482
3483
3484 .. _apireference-formeditor-basicjavascriptconcepts-events-view-collectionelement-removed:
3485
3486 view/collectionElement/removed
3487 ++++++++++++++++++++++++++++++
3488
3489 The method ``getFormEditorApp().getViewModel().removePropertyCollectionElement()``
3490 calls this event at the end. EXT:form uses this event to re-render the
3491 ``Inspector`` component as soon as a property collection element (validator/
3492 finisher) is removed.
3493
3494 Subscribe to the event:
3495
3496 .. code-block:: javascript
3497
3498 /**
3499 * @private
3500 *
3501 * @param string
3502 * @param array
3503 * args[0] = collectionElementIdentifier
3504 * args[1] = collectionName
3505 * args[2] = formElement
3506 * @return void
3507 */
3508 getPublisherSubscriber().subscribe('view/collectionElement/removed', function(topic, args) {
3509 });
3510
3511
3512 .. _apireference-formeditor-basicjavascriptconcepts-events-view-formelement-inserted:
3513
3514 view/formElement/inserted
3515 +++++++++++++++++++++++++
3516
3517 The method ``getFormEditorApp().getViewModel().createAndAddFormElement()`` and
3518 the event :ref:`view/insertElements/perform/after<apireference-formeditor-basicjavascriptconcepts-events-view-insertelements-perform-after>`
3519 call this event at the end. EXT:form uses this event to set the current
3520 to-be-processed form element (``getFormEditorApp().setCurrentlySelectedFormElement()``)
3521 and to re-render the ``Tree``, ``Stage`` and ``Inspector`` components.
3522
3523 Subscribe to the event:
3524
3525 .. code-block:: javascript
3526
3527 /**
3528 * @private
3529 *
3530 * @param string
3531 * @param array
3532 * args[0] = newFormElement
3533 * @return void
3534 */
3535 getPublisherSubscriber().subscribe('view/formElement/inserted', function(topic, args) {
3536 });
3537
3538
3539 .. _apireference-formeditor-basicjavascriptconcepts-events-view-formelement-moved:
3540
3541 view/formElement/moved
3542 ++++++++++++++++++++++
3543
3544 The method ``getFormEditorApp().getViewModel().moveFormElement()`` calls this
3545 event at the end.
3546
3547 Subscribe to the event:
3548
3549 .. code-block:: javascript
3550
3551 /**
3552 * @private
3553 *
3554 * @param string
3555 * @param array
3556 * args[0] = movedFormElement
3557 * @return void
3558 */
3559 getPublisherSubscriber().subscribe('view/formElement/moved', function(topic, args) {
3560 });
3561
3562
3563 .. _apireference-formeditor-basicjavascriptconcepts-events-view-formelement-removed:
3564
3565 view/formElement/removed
3566 ++++++++++++++++++++++++
3567
3568 The method ``getFormEditorApp().getViewModel().removeFormElement()`` calls this
3569 event at the end. EXT:form uses this event to set the current to-be-processed
3570 form element (``getFormEditorApp().setCurrentlySelectedFormElement()``) and to
3571 re-render the ``Tree``, ``Stage`` and ``Inspector`` components.
3572
3573 Subscribe to the event:
3574
3575 .. code-block:: javascript
3576
3577 /**
3578 * @private
3579 *
3580 * @param string
3581 * @param array
3582 * args[0] = parentFormElement
3583 * @return void
3584 */
3585 getPublisherSubscriber().subscribe('view/formElement/removed', function(topic, args) {
3586 });
3587
3588
3589 .. _apireference-formeditor-basicjavascriptconcepts-events-view-header-button-close-clicked:
3590
3591 view/header/button/close/clicked
3592 ++++++++++++++++++++++++++++++++
3593
3594 The onClick event of the "Close" button in the ``form editor's`` header section
3595 calls this event. EXT:form uses this event to display a warning message in case
3596 there are unsaved changes.
3597
3598 Subscribe to the event:
3599
3600 .. code-block:: javascript
3601
3602 /**
3603 * @private
3604 *
3605 * @param string
3606 * @param array
3607 * @return void
3608 */
3609 getPublisherSubscriber().subscribe('view/header/button/close/clicked', function(topic, args) {
3610 });
3611
3612
3613 .. _apireference-formeditor-basicjavascriptconcepts-events-view-header-button-newpage-clicked:
3614
3615 view/header/button/newPage/clicked
3616 ++++++++++++++++++++++++++++++++++
3617
3618 The onClick event of the "new page" button in the ``form editor's`` header
3619 section calls this event. EXT:form uses this event to display the "new page"
3620 dialog box.
3621
3622 Subscribe to the event:
3623
3624 .. code-block:: javascript
3625
3626 /**
3627 * @private
3628 *
3629 * @param string
3630 * @param array
3631 * args[0] = targetEvent
3632 * @return void
3633 */
3634 getPublisherSubscriber().subscribe('view/header/button/newPage/clicked', function(topic, args) {
3635 });
3636
3637
3638 .. _apireference-formeditor-basicjavascriptconcepts-events-view-header-button-save-clicked:
3639
3640 view/header/button/save/clicked
3641 +++++++++++++++++++++++++++++++
3642
3643 The onClick event of the "save" button in the ``form editor's`` header section
3644 calls this event. EXT:form uses this event either to display a dialog box with
3645 the element in question (if there are validation errors) or to save the ``form
3646 definition`` (if there are no validation errors).
3647
3648 Subscribe to the event:
3649
3650 .. code-block:: javascript
3651
3652 /**
3653 * @private
3654 *
3655 * @param string
3656 * @param array
3657 * @return void
3658 */
3659 getPublisherSubscriber().subscribe('view/header/button/save/clicked', function(topic, args) {
3660 });
3661
3662
3663 .. _apireference-formeditor-basicjavascriptconcepts-events-view-header-formsettings-clicked:
3664
3665 view/header/formSettings/clicked
3666 ++++++++++++++++++++++++++++++++
3667
3668 The onClick event of the "settings" button in the ``form editor's`` header
3669 section calls this event. EXT:form uses this event to select the root form
3670 element.
3671
3672 Subscribe to the event:
3673
3674 .. code-block:: javascript
3675
3676 /**
3677 * @private
3678 *
3679 * @param string
3680 * @param array
3681 * @return void
3682 */
3683 getPublisherSubscriber().subscribe('view/header/formSettings/clicked', function(topic, args) {
3684 });
3685
3686
3687 .. _apireference-formeditor-basicjavascriptconcepts-events-view-insertelements-perform-after:
3688
3689 view/insertElements/perform/after
3690 +++++++++++++++++++++++++++++++++
3691
3692 This event is called from the "new element" dialog box upon selection of a form
3693 element:
3694
3695 - if "After" in the "Create new element" split button in the form-element toolbar for composite elements (e.g. fieldset) is clicked.
3696 - if the "Create new element" button in the form-element toolbar for non-composite elements is clicked.
3697
3698 EXT:form uses this event to create a new form element (``getFormEditorApp().getViewModel().createAndAddFormElement()``)
3699 and then move (``getFormEditorApp().getViewModel().moveFormElement()``) it
3700 below the currently selected element (sibling). At the end of this event, the
3701 event :ref:`view/formElement/inserted<apireference-formeditor-basicjavascriptconcepts-events-view-formelement-inserted>`
3702 is called. The event ``view/formElement/inserted`` in ``getFormEditorApp().getViewModel().createAndAddFormElement()``
3703 was previously deactivated.
3704
3705 Subscribe to the event:
3706
3707 .. code-block:: javascript
3708
3709 /**
3710 * @private
3711 *
3712 * @param string
3713 * @param array
3714 * args[0] = formElementType
3715 * @return void
3716 */
3717 getPublisherSubscriber().subscribe('view/insertElements/perform/after', function(topic, args) {
3718 });
3719
3720
3721 .. _apireference-formeditor-basicjavascriptconcepts-events-view-insertelements-perform-bottom:
3722
3723 view/insertElements/perform/bottom
3724 ++++++++++++++++++++++++++++++++++
3725
3726 This event is called from the "new element" dialog box upon selection of a form
3727 element:
3728
3729 - if, in the ``abstract view`` mode, the "Create new element" button at the end of the ``Stage`` component is clicked.
3730
3731 EXT:form uses this event to create a new form element (``getFormEditorApp().getViewModel().createAndAddFormElement()``).
3732 This element is always created as the last element of the currently selected
3733 page.
3734
3735 Subscribe to the event:
3736
3737 .. code-block:: javascript
3738
3739 /**
3740 * @private
3741 *
3742 * @param string
3743 * @param array
3744 * args[0] = formElementType
3745 * @return void
3746 */
3747 getPublisherSubscriber().subscribe('view/insertElements/perform/bottom', function(topic, args) {
3748 });
3749
3750
3751 .. _apireference-formeditor-basicjavascriptconcepts-events-view-insertelements-perform-inside:
3752
3753 view/insertElements/perform/inside
3754 ++++++++++++++++++++++++++++++++++
3755
3756 This event is called from the "new element" dialog box upon selection of a form
3757 element:
3758
3759 - if "Inside" in the "Create new element" split button in the form-element toolbar for composite elements (e.g. fieldset) is clicked.
3760
3761 EXT:form uses this event to create a new form element as a child element of the
3762 currently selected element (``getFormEditorApp().getViewModel().createAndAddFormElement()``).
3763
3764 Subscribe to the event:
3765
3766 .. code-block:: javascript
3767
3768 /**
3769 * @private
3770 *
3771 * @param string
3772 * @param array
3773 * args[0] = formElementType
3774 * @return void
3775 */
3776 getPublisherSubscriber().subscribe('view/insertElements/perform/inside', function(topic, args) {
3777 });
3778
3779
3780 .. _apireference-formeditor-basicjavascriptconcepts-events-view-insertpages-perform:
3781
3782 view/insertPages/perform
3783 ++++++++++++++++++++++++
3784
3785 This event is called from the "new element" dialog box upon selection of a page
3786 element:
3787
3788 - if the "Create new page" icon in the header section is clicked.
3789 - if the "Create new page" button in the ``Tree`` component is clicked.
3790
3791 EXT:form uses this event to create a new page after the currently selected page
3792 (``getFormEditorApp().getViewModel().createAndAddFormElement()``).
3793
3794 Subscribe to the event:
3795
3796 .. code-block:: javascript
3797
3798 /**
3799 * @private
3800 *
3801 * @param string
3802 * @param array
3803 * args[0] = formElementType
3804 * @return void
3805 */
3806 getPublisherSubscriber().subscribe('view/insertPages/perform', function(topic, args) {
3807 });
3808
3809
3810 .. _apireference-formeditor-basicjavascriptconcepts-events-view-inspector-collectionelement-existing-selected:
3811
3812 view/inspector/collectionElement/existing/selected
3813 ++++++++++++++++++++++++++++++++++++++++++++++++++
3814
3815 The ``inspector editors`` :ref:`ValidatorsEditor <typo3.cms.form.prototypes.\<prototypeidentifier>.formelementsdefinition.\<formelementtypeidentifier>.formeditor.editors.*.finisherseditor>`
3816 and :ref:`FinishersEditor <typo3.cms.form.prototypes.\<prototypeidentifier>.formelementsdefinition.\<formelementtypeidentifier>.formeditor.editors.*.validatorseditor>`
3817 are used to display the available validators/ finishers for a form element as a
3818 select box. Furthermore, these ``inspector editors`` indicate that in the
3819 ``form definition``, validators/ finishers for the currently selected element
3820 already exist. This occurs through the event ``view/inspector/collectionElement/existing/selected``.
3821 EXT:form uses this event to render these validators/ finishers and their
3822 tentatively configured ``inspector editors`` (``getFormEditorApp().getViewModel().renderInspectorCollectionElementEditors()``).
3823
3824 Subscribe to the event:
3825
3826 .. code-block:: javascript
3827
3828 /**
3829 * @private
3830 *
3831 * @param string
3832 * @param array
3833 * args[0] = collectionElementIdentifier
3834 * args[1] = collectionName
3835 * @return void
3836 */
3837 getPublisherSubscriber().subscribe('view/inspector/collectionElement/existing/selected', function(topic, args) {
3838 });
3839
3840
3841 .. _apireference-formeditor-basicjavascriptconcepts-events-view-inspector-collectionelement-new-selected:
3842
3843 view/inspector/collectionElement/new/selected
3844 +++++++++++++++++++++++++++++++++++++++++++++
3845
3846 The ``inspector editors`` :ref:`ValidatorsEditor <typo3.cms.form.prototypes.\<prototypeidentifier>.formelementsdefinition.\<formelementtypeidentifier>.formeditor.editors.*.finisherseditor>`
3847 and :ref:`FinishersEditor <typo3.cms.form.prototypes.\<prototypeidentifier>.formelementsdefinition.\<formelementtypeidentifier>.formeditor.editors.*.validatorseditor>`
3848 are used to display the available validators/ finishers for a form element as a
3849 select box. The onChange event of the select box then calls this event. In
3850 addition, the ``inspector editor`` :ref:`RequiredValidatorEditor <typo3.cms.form.prototypes.\<prototypeidentifier>.formelementsdefinition.\<formelementtypeidentifier>.formeditor.editors.*.requiredvalidatoreditor>`
3851 calls this event when a checkbox is chosen. EXT:form uses this event to add and
3852 render the validator/ finisher of the ``form definition`` via ``getFormEditorApp().getViewModel().createAndAddPropertyCollectionElement()``.
3853
3854 Subscribe to the event:
3855
3856 .. code-block:: javascript
3857
3858 /**
3859 * @private
3860 *
3861 * @param string
3862 * @param array
3863 * args[0] = collectionElementIdentifier
3864 * args[1] = collectionName
3865 * @return void
3866 */
3867 getPublisherSubscriber().subscribe('view/inspector/collectionElement/new/selected', function(topic, args) {
3868 });
3869
3870
3871 .. _apireference-formeditor-basicjavascriptconcepts-events-view-inspector-collectionelement-dnd-update:
3872
3873 view/inspector/collectionElements/dnd/update
3874 ++++++++++++++++++++++++++++++++++++++++++++
3875
3876 EXT:form uses the jQuery plugin 'jquery.mjs.nestedSortable' for the drag-and-
3877 drop functionality. The 'update' event from 'jquery.mjs.nestedSortable' calls
3878 the ``view/inspector/collectionElements/dnd/update`` event if a property
3879 collection element in the ``Inspector`` component is sorted. EXT:form uses this
3880 event to move the validator/ finisher in the ``form definition`` via the method
3881 ``getFormEditorApp().getViewModel().movePropertyCollectionElement()``.
3882
3883 Subscribe to the event:
3884
3885 .. code-block:: javascript
3886
3887 /**
3888 * @private
3889 *
3890 * @param string
3891 * @param array
3892 * args[0] = movedCollectionElementIdentifier
3893 * args[1] = previousCollectionElementIdentifier
3894 * args[2] = nextCollectionElementIdentifier
3895 * args[3] = collectionName
3896 * @return void
3897 */
3898 getPublisherSubscriber().subscribe('view/inspector/collectionElements/dnd/update', function(topic, args) {
3899 });
3900
3901
3902 .. _apireference-formeditor-basicjavascriptconcepts-events-view-inspector-editor-insert-perform:
3903
3904 view/inspector/editor/insert/perform
3905 ++++++++++++++++++++++++++++++++++++
3906
3907 The methods ``getFormEditorApp().getViewModel().renderInspectorEditors()`` (to
3908 render all ``inspector editors`` for a form element) and ``getFormEditorApp().getViewModel().renderInspectorCollectionElementEditors()``
3909 (to render the ``inspector editors`` for a validator/ finisher) call this event
3910 at the end. Strictly speaking, the ``Inspector`` component in the method
3911 ``_renderEditorDispatcher()`` calls this event.
3912 Each ``inspector editor`` has the property :ref:`templateName <typo3.cms.form.prototypes.\<prototypeidentifier>.formelementsdefinition.\<formelementtypeidentifier>.formeditor.editors.*.templatename>`,
3913 which gives the ``form editor`` two pieces of information. On the one hand the
3914 ``templateName`` must match with a key within the :ref:`TYPO3.CMS.Form.prototypes.\<prototypeIdentifier>.formeditor.formEditorPartials <typo3.cms.form.prototypes.\<prototypeidentifier>.formeditor.formeditorpartials>`.
3915 The ``form editor`` can consequently load a corresponding inline HTML template
3916 for the ``inspector editor``. On the other hand, the ``Inspector`` component
3917 must be told which JavaScript code should be executed for the
3918 ``inspector editor``. For the ``inspector editors`` delivered with EXT:form,
3919 this occurs within the method ``_renderEditorDispatcher()``.
3920 An existing hard-coded list of known ``inspector editors`` determines, by means
3921 of the property ``templateName``, which corresponding JavaScript method should
3922 be executed for the ``inspector editor``. At the end, the event
3923 ``view/inspector/editor/insert/perform`` is called. If you wish to implement
3924 your own ``inspector editor``, you can use this event to execute in
3925 :ref:`your own JavaScript module <concepts-formeditor-basicjavascriptconcepts-registercustomjavascriptmodules>`.
3926 the corresponding JavaScript code, with the help of the property
3927 ``templateName``.
3928
3929 Subscribe to the event:
3930
3931 .. code-block:: javascript
3932
3933 /**
3934 * @private
3935 *
3936 * @param string
3937 * @param array
3938 * args[0] = editorConfiguration
3939 * args[1] = editorHtml
3940 * args[2] = collectionElementIdentifier
3941 * args[3] = collectionName
3942 * @return void
3943 */
3944 getPublisherSubscriber().subscribe('view/inspector/editor/insert/perform', function(topic, args) {
3945 });
3946
3947 A simple example that registers a custom ``inspector editor`` called 'Inspector-MyCustomInspectorEditor' and adds it to text form elements:
3948
3949 .. code-block:: yaml
3950
3951 TYPO3:
3952 CMS:
3953 Form:
3954 prototypes:
3955 standard:
3956 formEditor:
3957 dynamicRequireJsModules:
3958 additionalViewModelModules:
3959 10: 'TYPO3/CMS/MySitePackage/Backend/FormEditor/ViewModel'
3960 formEditorFluidConfiguration:
3961 partialRootPaths:
3962 100: 'EXT:my_site_package/Resources/Private/Backend/Partials/FormEditor/'
3963 formEditorPartials:
3964 Inspector-MyCustomInspectorEditor: 'Inspector/MyCustomInspectorEditor'
3965 formElementsDefinition:
3966 Text:
3967 formEditor:
3968 editors:
3969 600:
3970 templateName: 'Inspector-MyCustomInspectorEditor'
3971 ...
3972
3973 .. code-block:: javascript
3974 :emphasize-lines: 107-116
3975
3976 /**
3977 * Module: TYPO3/CMS/MySitePackage/Backend/FormEditor/ViewModel
3978 */
3979 define(['jquery',
3980 'TYPO3/CMS/Form/Backend/FormEditor/Helper'
3981 ], function($, Helper) {
3982 'use strict';
3983
3984 return (function($, Helper) {
3985
3986 /**
3987 * @private
3988 *
3989 * @var object
3990 */
3991 var _formEditorApp = null;
3992
3993 /**
3994 * @private
3995 *
3996 * @return object
3997 */
3998 function getFormEditorApp() {
3999 return _formEditorApp;
4000 };
4001
4002 /**
4003 * @private
4004 *
4005 * @return object
4006 */
4007 function getPublisherSubscriber() {
4008 return getFormEditorApp().getPublisherSubscriber();
4009 };
4010
4011 /**
4012 * @private
4013 *
4014 * @return object
4015 */
4016 function getUtility() {
4017 return getFormEditorApp().getUtility();
4018 };
4019
4020 /**
4021 * @private
4022 *
4023 * @param object
4024 * @return object
4025 */
4026 function getHelper() {
4027 return Helper;
4028 };
4029
4030 /**
4031 * @private
4032 *
4033 * @return object
4034 */
4035 function getCurrentlySelectedFormElement() {
4036 return getFormEditorApp().getCurrentlySelectedFormElement();
4037 };
4038
4039 /**
4040 * @private
4041 *
4042 * @param mixed test
4043 * @param string message
4044 * @param int messageCode
4045 * @return void
4046 */
4047 function assert(test, message, messageCode) {
4048 return getFormEditorApp().assert(test, message, messageCode);
4049 };
4050
4051 /**
4052 * @private
4053 *
4054 * @return void
4055 * @throws 1491643380
4056 */
4057 function _helperSetup() {
4058 assert('function' === $.type(Helper.bootstrap),
4059 'The view model helper does not implement the method "bootstrap"',
4060 1491643380
4061 );
4062 Helper.bootstrap(getFormEditorApp());
4063 };
4064
4065 /**
4066 * @private
4067 *
4068 * @return void
4069 */
4070 function _subscribeEvents() {
4071 /**
4072 * @private
4073 *
4074 * @param string
4075 * @param array
4076 * args[0] = editorConfiguration
4077 * args[1] = editorHtml
4078 * args[2] = collectionElementIdentifier
4079 * args[3] = collectionName
4080 * @return void
4081 */
4082 getPublisherSubscriber().subscribe('view/inspector/editor/insert/perform', function(topic, args) {
4083 if (args[0]['templateName'] === 'Inspector-MyCustomInspectorEditor') {
4084 renderMyCustomInspectorEditor(
4085 args[0],
4086 args[1],
4087 args[2],
4088 args[3]
4089 );
4090 }
4091 });
4092 };
4093
4094 /**
4095 * @private
4096 *
4097 * @param object editorConfiguration
4098 * @param object editorHtml
4099 * @param string collectionElementIdentifier
4100 * @param string collectionName
4101 * @return void
4102 */
4103 function renderMyCustomInspectorEditor(editorConfiguration, editorHtml, collectionElementIdentifier, collectionName) {
4104 // do cool stuff
4105 });
4106
4107 /**
4108 * @public
4109 *
4110 * @param object formEditorApp
4111 * @return void
4112 */
4113 function bootstrap(formEditorApp) {
4114 _formEditorApp = formEditorApp;
4115 _helperSetup();
4116 _subscribeEvents();
4117 };
4118
4119 /**
4120 * Publish the public methods.
4121 * Implements the "Revealing Module Pattern".
4122 */
4123 return {
4124 bootstrap: bootstrap
4125 };
4126 })($, Helper);
4127 });
4128
4129
4130 .. _apireference-formeditor-basicjavascriptconcepts-events-view-inspector-removecollectionelement-perform:
4131
4132 view/inspector/removeCollectionElement/perform
4133 ++++++++++++++++++++++++++++++++++++++++++++++
4134
4135 The ``inspector editor`` :ref:`RequiredValidatorEditor <typo3.cms.form.prototypes.\<prototypeidentifier>.formelementsdefinition.\<formelementtypeidentifier>.formeditor.editors.*.requiredvalidatoreditor>`
4136 calls this event, if the checkbox is deselected. EXT:form uses this event to
4137 remove the configured required validator ('NotEmpty') from the ``form
4138 definition`` through the method ``getFormEditorApp().getViewModel().removePropertyCollectionElement()``.
4139
4140 Subscribe to the event:
4141
4142 .. code-block:: javascript
4143
4144 /**
4145 * @private
4146 *
4147 * @param string
4148 * @param array
4149 * args[0] = collectionElementIdentifier
4150 * args[1] = collectionName
4151 * args[2] = formElement
4152 * @return void
4153 */
4154 getPublisherSubscriber().subscribe('view/inspector/removeCollectionElement/perform', function(topic, args) {
4155 });
4156
4157
4158 .. _apireference-formeditor-basicjavascriptconcepts-events-view-modal-close-perform:
4159
4160 view/modal/close/perform
4161 ++++++++++++++++++++++++
4162
4163 If you try to close the ``form editor`` with unsaved content, a dialog box
4164 appears, asking whether you really wish to close it. If you confirm it, this
4165 event is called in the ``check box`` component. EXT:form uses this event to
4166 close the ``form editor`` and return to the ``form manager``.
4167
4168 Subscribe to the event:
4169
4170 .. code-block:: javascript
4171
4172 /**
4173 * @private
4174 *
4175 * @param string
4176 * @param array
4177 * @return void
4178 */
4179 getPublisherSubscriber().subscribe('view/modal/close/perform', function(topic, args) {
4180 });
4181
4182
4183 .. _apireference-formeditor-basicjavascriptconcepts-events-view-modal-removecollectionelement-perform:
4184
4185 view/modal/removeCollectionElement/perform
4186 ++++++++++++++++++++++++++++++++++++++++++
4187
4188 If you try to remove a validator/ finisher by clicking the remove icon, a
4189 dialog box appears, asking you to confirm this action. If confirmed, this event
4190 is called in the ``check box`` component. EXT:form uses this event to remove
4191 the validator/ finisher from the ``form definition`` through the method
4192 ``getFormEditorApp().getViewModel().removePropertyCollectionElement()``.
4193
4194 Subscribe to the event:
4195
4196 .. code-block:: javascript
4197
4198 /**
4199 * @private
4200 *
4201 * @param string
4202 * @param array
4203 * args[0] = collectionElementIdentifier
4204 * args[1] = collectionName
4205 * args[2] = formElement
4206 * @return void
4207 */
4208 getPublisherSubscriber().subscribe('view/modal/removeCollectionElement/perform', function(topic, args) {
4209 });
4210
4211
4212 .. _apireference-formeditor-basicjavascriptconcepts-events-view-modal-removeformelement-perform:
4213
4214 view/modal/removeFormElement/perform
4215 ++++++++++++++++++++++++++++++++++++
4216
4217 If you try to remove a form element by clicking the remove icon, a dialog box
4218 appears, asking you to confirm this action. If confirmed, this event is called
4219 in the ``check box`` component. EXT:form uses this event to remove the form
4220 element from the ``form definition`` via the method ``getFormEditorApp().getViewModel().removeFormElement()``.
4221
4222 Subscribe to the event:
4223
4224 .. code-block:: javascript
4225
4226 /**
4227 * @private
4228 *
4229 * @param string
4230 * @param array
4231 * args[0] = formElement
4232 * @return void
4233 */
4234 getPublisherSubscriber().subscribe('view/modal/removeFormElement/perform', function(topic, args) {
4235 });
4236
4237
4238 .. _apireference-formeditor-basicjavascriptconcepts-events-view-modal-validationerrors-element-clicked:
4239
4240 view/modal/validationErrors/element/clicked
4241 +++++++++++++++++++++++++++++++++++++++++++
4242
4243 If a form element contains a validation error and you try to save the form, a
4244 dialog box appears, listing all form elements with validation errors. One such
4245 form element can be clicked in this dialog box. This event is called by
4246 clicking a form element in the dialog box. EXT:form uses this event to select
4247 and show this form element.
4248
4249 Subscribe to the event:
4250
4251 .. code-block:: javascript
4252
4253 /**
4254 * @private
4255 *
4256 * @param string
4257 * @param array
4258 * args[0] = formElementIdentifierPath
4259 * @return void
4260 */
4261 getPublisherSubscriber().subscribe('view/modal/validationErrors/element/clicked', function(topic, args) {
4262 });
4263
4264
4265 .. _apireference-formeditor-basicjavascriptconcepts-events-view-paginationnext-clicked:
4266
4267 view/paginationNext/clicked
4268 +++++++++++++++++++++++++++
4269
4270 This event is called if the 'pagination next' button in the ``Stage``
4271 component's header section is clicked. EXT:form uses this event to render the
4272 next page of the form.
4273
4274 Subscribe to the event:
4275
4276 .. code-block:: javascript
4277
4278 /**
4279 * @private
4280 *
4281 * @param string
4282 * @param array
4283 * @return void
4284 */
4285 getPublisherSubscriber().subscribe('view/paginationNext/clicked', function(topic, args) {
4286 });
4287
4288
4289 .. _apireference-formeditor-basicjavascriptconcepts-events-view-paginationprevious-clicked:
4290
4291 view/paginationPrevious/clicked
4292 +++++++++++++++++++++++++++++++
4293
4294 This event is called, if the 'pagination previous' button in the ``Stage``
4295 component's header section is clicked. EXT:form uses this event to render the
4296 previous page of the form.
4297
4298 Subscribe to the event:
4299
4300 .. code-block:: javascript
4301
4302 /**
4303 * @private
4304 *
4305 * @param string
4306 * @param array
4307 * @return void
4308 */
4309 getPublisherSubscriber().subscribe('view/paginationPrevious/clicked', function(topic, args) {
4310 });
4311
4312
4313 .. _apireference-formeditor-basicjavascriptconcepts-events-view-ready:
4314
4315 view/ready
4316 ++++++++++
4317
4318 EXT:form makes it possible to load :ref:`your own JavaScript module <concepts-formeditor-basicjavascriptconcepts-registercustomjavascriptmodules>`.
4319 If all modules are loaded, the view-model method ``_loadAdditionalModules``
4320 calls this event. EXT:form uses this event to remove the preloader icon and
4321 finally initialize the ``form editor``.
4322
4323 Subscribe to the event:
4324
4325 .. code-block:: javascript
4326
4327 /**
4328 * @private
4329 *
4330 * @param string
4331 * @param array
4332 * @return void
4333 */
4334 getPublisherSubscriber().subscribe('view/ready', function(topic, args) {
4335 });
4336
4337
4338 .. _apireference-formeditor-basicjavascriptconcepts-events-view-redobutton-clicked:
4339
4340 view/redoButton/clicked
4341 +++++++++++++++++++++++
4342
4343 This event is called if the redo button in the ``form editor`` header is
4344 clicked. The addition/ deletion and movement of form elements and property
4345 collection elements (validators/ finishers) is saved in an internal stack in
4346 order to reset the undo/ redo functionality. EXT:form uses this event to reset
4347 this stack to the previous state.
4348
4349 Subscribe to the event:
4350
4351 .. code-block:: javascript
4352
4353 /**
4354 * @private
4355 *
4356 * @param string
4357 * @param array
4358 * @return void
4359 */
4360 getPublisherSubscriber().subscribe('view/redoButton/clicked', function(topic, args) {
4361 });
4362
4363
4364 .. _apireference-formeditor-basicjavascriptconcepts-events-view-stage-abstract-button-newelement-clicked:
4365
4366 view/stage/abstract/button/newElement/clicked
4367 +++++++++++++++++++++++++++++++++++++++++++++
4368
4369 This event is called if the "Create new element" button at the end of the
4370 ``Stage`` component in the ``abstract view`` mode is clicked. EXT:form uses
4371 this event to display the "new element" dialog box.
4372
4373 Subscribe to the event:
4374
4375 .. code-block:: javascript
4376
4377 /**
4378 * @private
4379 *
4380 * @param string
4381 * @param array
4382 * args[0] = targetEvent
4383 * args[1] = configuration
4384 * @return void
4385 */
4386 getPublisherSubscriber().subscribe('view/stage/abstract/button/newElement/clicked', function(topic, args) {
4387 });
4388
4389
4390 .. _apireference-formeditor-basicjavascriptconcepts-events-view-stage-abstract-dnd-change:
4391
4392 view/stage/abstract/dnd/change
4393 ++++++++++++++++++++++++++++++
4394
4395 EXT:form uses the jQuery plugin 'jquery.mjs.nestedSortable' for the drag-and-
4396 drop functionality. The 'change' event from 'jquery.mjs.nestedSortable' calls
4397 the ``view/stage/abstract/dnd/change`` event in the ``Stage`` component in the
4398 ``abstract view`` mode if form elements are sorted. EXT:form uses this event to
4399 set various CSS classes during the drag-and-drop process.
4400
4401 Subscribe to the event:
4402
4403 .. code-block:: javascript
4404
4405 /**
4406 * @private
4407 *
4408 * @param string
4409 * @param array
4410 * args[0] = placeholderDomElement
4411 * args[1] = parentFormElementIdentifierPath
4412 * args[2] = enclosingCompositeFormElement
4413 * @return void
4414 */
4415 getPublisherSubscriber().subscribe('view/stage/abstract/dnd/change', function(topic, args) {
4416 });
4417
4418
4419 .. _apireference-formeditor-basicjavascriptconcepts-events-view-stage-abstract-dnd-start:
4420
4421 view/stage/abstract/dnd/start
4422 +++++++++++++++++++++++++++++
4423
4424 EXT:form uses the jQuery plugin 'jquery.mjs.nestedSortable' for the drag-and-
4425 drop functionality. The 'start' event from 'jquery.mjs.nestedSortable' calls
4426 the ``view/stage/abstract/dnd/start`` event in the ``Stage`` component in the
4427 ``abstract view`` mode if form elements are sorted. EXT:form uses this event to
4428 set various CSS classes at the start of the drag-and-drop process.
4429
4430 Subscribe to the event:
4431
4432 .. code-block:: javascript
4433
4434 /**
4435 * @private
4436 *
4437 * @param string
4438 * @param array
4439 * args[0] = draggedFormElementDomElement
4440 * args[1] = draggedFormPlaceholderDomElement
4441 * @return void
4442 */
4443 getPublisherSubscriber().subscribe('view/stage/abstract/dnd/start', function(topic, args) {
4444 });
4445
4446
4447 .. _apireference-formeditor-basicjavascriptconcepts-events-view-stage-abstract-dnd-stop:
4448
4449 view/stage/abstract/dnd/stop
4450 ++++++++++++++++++++++++++++
4451
4452 EXT:form uses the jQuery plugin 'jquery.mjs.nestedSortable' for the drag-and-
4453 drop functionality. The 'stop' event from 'jquery.mjs.nestedSortable' calls the
4454 ``view/stage/abstract/dnd/stop`` event in the ``Stage`` component in the
4455 ``abstract view`` mode if form elements are sorted. EXT:form uses this event to
4456 to re-render the ``Tree``, ``Stage`` and ``Inspector`` components at the end of
4457 the drag-and-drop process and to select the moved form element.
4458
4459 Subscribe to the event:
4460
4461 .. code-block:: javascript