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