[TASK] EXT:form - explain initializeFormElement hook
[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 Note that this hook will be called **after** all properties from the prototype configuration are set in the form element but **before** the properties from
1503 the form definition are set in the form element.
1504 If you want to prefill form element data after the complete form element is configured you should use the :ref:`afterBuildingFinished<apireference-frontendrendering-runtimemanipulation-hooks-afterbuildingfinished>` hook.
1505
1506
1507 This hook is invoked by the methods ``TYPO3\CMS\Form\Domain\Model\FormElements\Page::createElement()`` and ``TYPO3\CMS\Form\Domain\Model\FormElements\Section::createElement()``.
1508 That means the hook will **not** be triggered for ``Pages``.
1509 At this point you don't have access to submitted form element values.
1510
1511
1512 .. _apireference-frontendrendering-runtimemanipulation-hooks-initializeformelement-connect:
1513
1514 Connect to the hook
1515 '''''''''''''''''''
1516
1517 .. code-block:: php
1518
1519 $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['initializeFormElement'][<useATimestampAsKeyPlease>]
1520 = \VENDOR\YourNamespace\YourClass::class;
1521
1522
1523 .. _apireference-frontendrendering-runtimemanipulation-hooks-initializeformelement-use:
1524
1525 Use the hook
1526 ''''''''''''
1527
1528 .. code-block:: php
1529
1530 /**
1531 * @param \TYPO3\CMS\Form\Domain\Model\Renderable\RenderableInterface $renderable
1532 * @return void
1533 */
1534 public function initializeFormElement(\TYPO3\CMS\Form\Domain\Model\Renderable\RenderableInterface $renderable)
1535 {
1536 if ($renderable->getUniqueIdentifier() === 'contactForm-text-1') {
1537 $renderable->setDefaultValue('foo');
1538 }
1539 }
1540
1541
1542 .. _apireference-frontendrendering-runtimemanipulation-hooks-beforeremovefromparentrenderable:
1543
1544 beforeRemoveFromParentRenderable
1545 ++++++++++++++++++++++++++++++++
1546
1547 This hook is invoked by the methods ``TYPO3\CMS\Form\Domain\Model\FormDefinition::removePage()``, ``TYPO3\CMS\Form\Domain\Model\FormElements\Page::removeElement()``
1548 and ``TYPO3\CMS\Form\Domain\Model\FormElements\Section::removeElement()``
1549
1550
1551 .. _apireference-frontendrendering-runtimemanipulation-hooks-beforeremovefromparentrenderable-connect:
1552
1553 Connect to the hook
1554 '''''''''''''''''''
1555
1556 .. code-block:: php
1557
1558 $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['beforeRemoveFromParentRenderable'][<useATimestampAsKeyPlease>]
1559 = \VENDOR\YourNamespace\YourClass::class;
1560
1561
1562 .. _apireference-frontendrendering-runtimemanipulation-hooks-beforeremovefromparentrenderable-use:
1563
1564 Use the hook
1565 ''''''''''''
1566
1567 .. code-block:: php
1568
1569 /**
1570 * @param \TYPO3\CMS\Form\Domain\Model\Renderable\RenderableInterface $renderable
1571 * @return void
1572 */
1573 public function beforeRemoveFromParentRenderable(\TYPO3\CMS\Form\Domain\Model\Renderable\RenderableInterface $renderable)
1574 {
1575 }
1576
1577
1578 .. _apireference-frontendrendering-runtimemanipulation-hooks-afterbuildingfinished:
1579
1580 afterBuildingFinished
1581 +++++++++++++++++++++
1582
1583 This hook is called for each form element after the class ``TYPO3\CMS\Form\Domain\Factory\ArrayFormFactory``
1584 has built the entire form. This hook is triggered just before the
1585 ``FormRuntime`` object is generated. At this point, no run-time information
1586 (e.g. assigned form values) is yet available. It can, for example, be used to
1587 generate new form elements within complex forms. The ``ArrayFormFactory`` is
1588 used by EXT:form via the ``RenderViewHelper`` to render forms using a ``form
1589 definition`` YAML file. Each form factory implementation must deal with the
1590 calling of this hook themselves. EXT:form itself uses this hook to initialize
1591 the property-mapper configuration for ``FileUpload`` elements.
1592
1593 .. _apireference-frontendrendering-runtimemanipulation-hooks-afterbuildingfinished-connect:
1594
1595 Connect to the hook
1596 '''''''''''''''''''
1597
1598 .. code-block:: php
1599
1600 $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['afterBuildingFinished'][<useATimestampAsKeyPlease>]
1601 = \VENDOR\YourNamespace\YourClass::class;
1602
1603
1604 .. _apireference-frontendrendering-runtimemanipulation-hooks-afterbuildingfinished-use:
1605
1606 Use the hook
1607 ''''''''''''
1608
1609 .. code-block:: php
1610
1611 /**
1612 * @param \TYPO3\CMS\Form\Domain\Model\Renderable\RenderableInterface $renderable
1613 * @return void
1614 */
1615 public function afterBuildingFinished(\TYPO3\CMS\Form\Domain\Model\Renderable\RenderableInterface $renderable)
1616 {
1617 }
1618
1619
1620 .. _apireference-frontendrendering-runtimemanipulation-hooks-afterinitializecurrentpage:
1621
1622 afterInitializeCurrentPage
1623 ++++++++++++++++++++++++++
1624
1625 EXT:form automatically detects the page that should be shown and allow users
1626 only to jump to the directly following (or previous) pages. This hook enables
1627 you to implement a custom behavior, for example pages that are shown only when
1628 other form elements have specific values.
1629
1630
1631 .. _apireference-frontendrendering-runtimemanipulation-hooks-afterinitializecurrentpage-connect:
1632
1633 Connect to the hook
1634 '''''''''''''''''''
1635
1636 .. code-block:: php
1637
1638 $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['afterInitializeCurrentPage'][<useATimestampAsKeyPlease>]
1639 = \VENDOR\YourNamespace\YourClass::class;
1640
1641
1642 .. _apireference-frontendrendering-runtimemanipulation-hooks-afterinitializecurrentpage-use:
1643
1644 Use the hook
1645 ''''''''''''
1646
1647 .. code-block:: php
1648
1649 /**
1650 * @param \TYPO3\CMS\Form\Domain\Runtime\FormRuntime $formRuntime
1651 * @param \TYPO3\CMS\Form\Domain\Model\Renderable\CompositeRenderableInterface $currentPage
1652 * @param null|\TYPO3\CMS\Form\Domain\Model\Renderable\CompositeRenderableInterface $lastPage
1653 * @param mixed $elementValue submitted value of the element *before post processing*
1654 * @return \TYPO3\CMS\Form\Domain\Model\Renderable\CompositeRenderableInterface
1655 */
1656 public function afterInitializeCurrentPage(\TYPO3\CMS\Form\Domain\Runtime\FormRuntime $formRuntime, \TYPO3\CMS\Form\Domain\Model\Renderable\CompositeRenderableInterface $currentPage, \TYPO3\CMS\Form\Domain\Model\Renderable\CompositeRenderableInterface $lastPage = null, array $requestArguments = []): \TYPO3\CMS\Form\Domain\Model\Renderable\CompositeRenderableInterface
1657 {
1658 return $currentPage;
1659 }
1660
1661
1662 .. _apireference-frontendrendering-runtimemanipulation-hooks-aftersubmit:
1663
1664 afterSubmit
1665 +++++++++++
1666
1667 You can use it for example for dynamic validations which depends on other submitted form element values.
1668 This hook is invoked by the ``FormRuntime`` for each form element **before** values are property mapped, validated and pushed within the FormRuntime's ``FormState``.
1669 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
1670 the submitted form element values from the first page. In this case you can access the submitted raw data through ``$requestArguments``.
1671 EXT:form itself uses this hook to dynamically add validation errors for ``AdvancedPassword`` form elements.
1672
1673
1674 .. _apireference-frontendrendering-runtimemanipulation-hooks-aftersubmit-connect:
1675
1676 Connect to the hook
1677 '''''''''''''''''''
1678
1679 .. code-block:: php
1680
1681 $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['afterSubmit'][<useATimestampAsKeyPlease>]
1682 = \VENDOR\YourNamespace\YourClass::class;
1683
1684
1685 .. _apireference-frontendrendering-runtimemanipulation-hooks-aftersubmit-use:
1686
1687 Use the hook
1688 ''''''''''''
1689
1690 .. code-block:: php
1691
1692 /**
1693 * @param \TYPO3\CMS\Form\Domain\Runtime\FormRuntime $formRuntime
1694 * @param \TYPO3\CMS\Form\Domain\Model\Renderable\RenderableInterface $renderable
1695 * @param mixed $elementValue submitted value of the element *before post processing*
1696 * @param array $requestArguments submitted raw request values
1697 * @return void
1698 */
1699 public function afterSubmit(\TYPO3\CMS\Form\Domain\Runtime\FormRuntime $formRuntime, \TYPO3\CMS\Form\Domain\Model\Renderable\RenderableInterface $renderable, $elementValue, array $requestArguments = [])
1700 {
1701 return $elementValue;
1702 }
1703
1704
1705 .. _apireference-frontendrendering-runtimemanipulation-hooks-beforerendering:
1706
1707 beforeRendering
1708 +++++++++++++++
1709
1710 This is a hook that is invoked by the rendering system before the corresponding element is rendered.
1711 Use this to access previously submitted values and/or modify the ``FormRuntime`` before an element is outputted to the browser.
1712 This hook is called after all validations and property mappings are done.
1713
1714 .. _apireference-frontendrendering-runtimemanipulation-hooks-beforerendering-connect:
1715
1716 Connect to the hook
1717 '''''''''''''''''''
1718
1719 .. code-block:: php
1720
1721 $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['beforeRendering'][<useATimestampAsKeyPlease>]
1722 = \VENDOR\YourNamespace\YourClass::class;
1723
1724
1725 .. _apireference-frontendrendering-runtimemanipulation-hooks-beforerendering-use:
1726
1727 Use the hook
1728 ''''''''''''
1729
1730 .. code-block:: php
1731
1732 /**
1733 * @param \TYPO3\CMS\Form\Domain\Runtime\FormRuntime $formRuntime
1734 * @param \TYPO3\CMS\Form\Domain\Model\Renderable\RootRenderableInterface $renderable
1735 * @return void
1736 */
1737 public function beforeRendering(\TYPO3\CMS\Form\Domain\Runtime\FormRuntime $formRuntime, \TYPO3\CMS\Form\Domain\Model\Renderable\RootRenderableInterface $renderable)
1738 {
1739 }
1740
1741
1742 .. _apireference-finisheroptions:
1743
1744 Finisher Options
1745 ================
1746
1747 .. _apireference-finisheroptions-closurefinisher:
1748
1749 Closure finisher
1750 ----------------
1751
1752 This finisher can only be used in programmatically-created forms. It makes it
1753 possible to execute one's own finisher code without having to implement/
1754 declare this finisher.
1755
1756 Usage through code:
1757
1758 .. code-block:: php
1759
1760 $closureFinisher = $this->objectManager->get(ClosureFinisher::class);
1761 $closureFinisher->setOption('closure', function($finisherContext) {
1762 $formRuntime = $finisherContext->getFormRuntime();
1763 // ...
1764 });
1765 $formDefinition->addFinisher($closureFinisher);
1766
1767
1768 .. _apireference-finisheroptions-closurefinisher-options:
1769
1770 Options
1771 ^^^^^^^
1772
1773 .. _apireference-finisheroptions-closurefinisher-options-closure:
1774
1775 closure
1776 +++++++
1777
1778 :aspect:`Data type`
1779 \Closure
1780
1781 :aspect:`Mandatory`
1782 Yes
1783
1784 :aspect:`Default value`
1785 null
1786
1787
1788 .. _apireference-finisheroptions-confirmationfinisher:
1789
1790 Confirmation finisher
1791 ---------------------
1792
1793 A simple finisher that outputs a given text.
1794
1795 Usage within form definition
1796
1797 .. code-block:: yaml
1798
1799 identifier: example-form
1800 label: 'example'
1801 type: Form
1802
1803 finishers:
1804 -
1805 identifier: Confirmation
1806 options:
1807 message: 'Thx for using TYPO3'
1808 ...
1809
1810
1811 Usage through code:
1812
1813 .. code-block:: php
1814
1815 $formDefinition->createFinisher('Confirmation', [
1816 'message' => 'foo',
1817 ]);
1818
1819 or create manually (not preferred)
1820
1821 .. code-block:: php
1822
1823 $confirmationFinisher = $this->objectManager->get(ConfirmationFinisher::class);
1824 $confirmationFinisher->setOptions([
1825 'message' => 'foo',
1826 ]);
1827 $formDefinition->addFinisher($confirmationFinisher);
1828
1829
1830 .. _apireference-finisheroptions-confirmationfinisher-options:
1831
1832 Options
1833 ^^^^^^^
1834
1835 .. _apireference-finisheroptions-confirmationfinisher-options-message:
1836
1837 message
1838 +++++++
1839
1840 :aspect:`Data type`
1841 string
1842
1843 :aspect:`Mandatory`
1844 Yes
1845
1846 :aspect:`Default value`
1847 The form has been submitted.
1848
1849
1850 .. _apireference-finisheroptions-deleteuploadsfinisher:
1851
1852 DeleteUploads finisher
1853 ----------------------
1854
1855 This finisher remove the currently submited files.
1856 Use this finisher e.g after the email finisher if you don't want to keep the files online.
1857
1858
1859 Usage within form definition
1860
1861 .. code-block:: yaml
1862
1863 identifier: example-form
1864 label: 'example'
1865 type: Form
1866
1867 finishers:
1868 -
1869 identifier: DeleteUploads
1870 ...
1871
1872
1873 Usage through code:
1874
1875 .. code-block:: php
1876
1877 $formDefinition->createFinisher('DeleteUploads');
1878
1879 or create manually (not preferred)
1880
1881 .. code-block:: php
1882
1883 $deleteUploadsFinisher = $this->objectManager->get(DeleteUploadsFinisher::class);
1884 $formDefinition->addFinisher($deleteUploadsFinisher);
1885
1886
1887 .. _apireference-finisheroptions-emailfinisher:
1888
1889 Email finisher
1890 --------------
1891
1892 This finisher sends an email to one recipient.
1893 EXT:form uses 2 EmailFinisher declarations with the identifiers ``EmailToReceiver`` and ``EmailToSender``.
1894
1895 Usage within form definition
1896
1897 .. code-block:: yaml
1898
1899 identifier: example-form
1900 label: 'example'
1901 type: Form
1902
1903 finishers:
1904 -
1905 identifier: EmailToReceiver
1906 options:
1907 subject: 'Your message'
1908 recipientAddress: your.company@example.com
1909 recipientName: 'Your Company name'
1910 senderAddress: 'form@example.com'
1911 senderName: 'form submitter'
1912 ...
1913
1914
1915 Usage through code:
1916
1917 .. code-block:: php
1918
1919 $formDefinition->createFinisher('EmailToReceiver', [
1920 'subject' => 'Your message',
1921 'recipientAddress' => 'your.company@example.com',
1922 'recipientName' => 'Your Company name',
1923 'senderAddress' => 'form@example.com',
1924 'senderName' => 'form submitter',
1925 ]);
1926
1927 or create manually (not preferred)
1928
1929 .. code-block:: php
1930
1931 $emailFinisher = $this->objectManager->get(EmailFinisher::class);
1932 $emailFinisher->setOptions([
1933 'subject' => 'Your message',
1934 'recipientAddress' => 'your.company@example.com',
1935 'recipientName' => 'Your Company name',
1936 'senderAddress' => 'form@example.com',
1937 'senderName' => 'form submitter',
1938 ]);
1939 $formDefinition->addFinisher($emailFinisher);
1940
1941
1942 .. _apireference-finisheroptions-emailfinisher-options:
1943
1944 Options
1945 ^^^^^^^
1946
1947 .. _apireference-finisheroptions-emailfinisher-options-subject:
1948
1949 subject
1950 +++++++
1951
1952 :aspect:`Data type`
1953 string
1954
1955 :aspect:`Mandatory`
1956 Yes
1957
1958 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
1959 undefined
1960
1961 :aspect:`Description`
1962 Subject of the email
1963
1964
1965 .. _apireference-finisheroptions-emailfinisher-options-recipientaddress:
1966
1967 recipientAddress
1968 ++++++++++++++++
1969
1970 :aspect:`Data type`
1971 string
1972
1973 :aspect:`Mandatory`
1974 Yes
1975
1976 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
1977 undefined
1978
1979 :aspect:`Description`
1980 Email address of the recipient (To)
1981
1982
1983 .. _apireference-finisheroptions-emailfinisher-options-recipientname:
1984
1985 recipientName
1986 +++++++++++++
1987
1988 :aspect:`Data type`
1989 string
1990
1991 :aspect:`Mandatory`
1992 No
1993
1994 :aspect:`Default value`
1995 empty string
1996
1997 :aspect:`Description`
1998 Human-readable name of the recipient
1999
2000
2001 .. _apireference-finisheroptions-emailfinisher-options-senderaddress:
2002
2003 senderAddress
2004 +++++++++++++
2005
2006 :aspect:`Data type`
2007 string
2008
2009 :aspect:`Mandatory`
2010 Yes
2011
2012 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
2013 undefined
2014
2015 :aspect:`Description`
2016 Email address of the sender/ visitor (From)
2017
2018
2019 .. _apireference-finisheroptions-emailfinisher-options-sendername:
2020
2021 senderName
2022 ++++++++++
2023
2024 :aspect:`Data type`
2025 string
2026
2027 :aspect:`Mandatory`
2028 No
2029
2030 :aspect:`Default value`
2031 empty string
2032
2033 :aspect:`Description`
2034 Human-readable name of the sender
2035
2036
2037 .. _apireference-finisheroptions-emailfinisher-options-replytoaddress:
2038
2039 replyToAddress
2040 ++++++++++++++
2041
2042 :aspect:`Data type`
2043 string/ array
2044
2045 :aspect:`Mandatory`
2046 No
2047
2048 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
2049 undefined
2050
2051 :aspect:`Description`
2052 Email address of to be used as reply-to email (use multiple addresses with an array)
2053
2054 .. note::
2055 For the moment, the ``form editor`` cannot deal with multiple reply-to addresses (use multiple addresses with an array)
2056
2057
2058 .. _apireference-finisheroptions-emailfinisher-options-carboncopyaddress:
2059
2060 carbonCopyAddress
2061 +++++++++++++++++
2062
2063 :aspect:`Data type`
2064 string/ array
2065
2066 :aspect:`Mandatory`
2067 No
2068
2069 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
2070 undefined
2071
2072 :aspect:`Description`
2073 Email address of the copy recipient (use multiple addresses with an array)
2074
2075 .. note::
2076 For the moment, the ``form editor`` cannot deal with multiple copy recipient addresses (use multiple addresses with an array)
2077
2078
2079 .. _apireference-finisheroptions-emailfinisher-options-blindcarboncopyaddress:
2080
2081 blindCarbonCopyAddress
2082 ++++++++++++++++++++++
2083
2084 :aspect:`Data type`
2085 string/ array
2086
2087 :aspect:`Mandatory`
2088 No
2089
2090 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
2091 undefined
2092
2093 :aspect:`Description`
2094 Email address of the blind copy recipient (use multiple addresses with an array)
2095
2096 .. note::
2097 For the moment, the ``form editor`` cannot deal with multiple blind copy recipient addresses (use multiple addresses with an array)
2098
2099
2100 .. _apireference-finisheroptions-emailfinisher-options-format:
2101
2102 format
2103 ++++++
2104
2105 :aspect:`Data type`
2106 string
2107
2108 :aspect:`Mandatory`
2109 No
2110
2111 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
2112 html
2113
2114 :aspect:`possible values`
2115 html/ plaintext
2116
2117 :aspect:`Description`
2118 The format of the email. By default mails are sent as HTML.
2119
2120
2121 .. _apireference-finisheroptions-emailfinisher-options-attachuploads:
2122
2123 attachUploads
2124 +++++++++++++
2125
2126 :aspect:`Data type`
2127 bool
2128
2129 :aspect:`Mandatory`
2130 No
2131
2132 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
2133 true
2134
2135 :aspect:`Description`
2136 If set, all uploaded items are attached to the email.
2137
2138
2139 .. _apireference-finisheroptions-emailfinisher-options-translation-translationfile:
2140
2141 translation.translationFile
2142 +++++++++++++++++++++++++++
2143
2144 :aspect:`Data type`
2145 string/ array
2146
2147 :aspect:`Mandatory`
2148 No
2149
2150 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
2151 undefined
2152
2153 :aspect:`Description`
2154 If set, this translation file(s) will be used for finisher option translations.
2155 If not set, the translation file(s) from the 'Form' element will be used.
2156 Read :ref:`Translate finisher options<concepts-frontendrendering-translation-finishers>` for more informations.
2157
2158
2159 .. _apireference-finisheroptions-emailfinisher-options-translation-language:
2160
2161 translation.language
2162 ++++++++++++++++++++
2163
2164 :aspect:`Data type`
2165 string
2166
2167 :aspect:`Mandatory`
2168 No
2169
2170 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
2171 undefined
2172
2173 :aspect:`Description`
2174 If not set, the finisher options are translated depending on the current frontend language (if translations exists).
2175 This option allows you to force translations for a given sys_language isocode, e.g 'dk' or 'de'.
2176 Read :ref:`Translate finisher options<concepts-frontendrendering-translation-finishers>` for more informations.
2177
2178
2179 .. _apireference-finisheroptions-emailfinisher-options-templatepathandfilename:
2180
2181 templatePathAndFilename
2182 +++++++++++++++++++++++
2183
2184 :aspect:`Data type`
2185 string
2186
2187 :aspect:`Mandatory`
2188 Yes
2189
2190 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
2191 'EXT:form/Resources/Private/Frontend/Templates/Finishers/Email/{@format}.html'
2192
2193 :aspect:`Description`
2194 Template path and filename for the mail body.
2195 The placeholder {\@format} will be replaced with the value from option ``format``
2196
2197
2198 .. _apireference-finisheroptions-emailfinisher-options-layoutrootpaths:
2199
2200 layoutRootPaths
2201 +++++++++++++++
2202
2203 :aspect:`Data type`
2204 array
2205
2206 :aspect:`Mandatory`
2207 No
2208
2209 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
2210 undefined
2211
2212 :aspect:`Description`
2213 Fluid layout paths
2214
2215
2216 .. _apireference-finisheroptions-emailfinisher-options-partialrootpaths:
2217
2218 partialRootPaths
2219 ++++++++++++++++
2220
2221 :aspect:`Data type`
2222 array
2223
2224 :aspect:`Mandatory`
2225 No
2226
2227 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
2228 undefined
2229
2230 :aspect:`Description`
2231 Fluid partial paths
2232
2233
2234 .. _apireference-finisheroptions-emailfinisher-options-variables:
2235
2236 variables
2237 +++++++++
2238
2239 :aspect:`Data type`
2240 array
2241
2242 :aspect:`Mandatory`
2243 No
2244
2245 :aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
2246 undefined
2247
2248 :aspect:`Description`
2249 associative array of variables which are available inside the Fluid template
2250
2251
2252 .. _apireference-finisheroptions-flashmessagefinisher:
2253
2254 FlashMessage finisher
2255 ---------------------
2256
2257 A simple finisher that adds a message to the FlashMessageContainer.
2258
2259
2260 Usage within form definition
2261
2262 .. code-block:: yaml
2263
2264 identifier: example-form
2265 label: 'example'
2266 type: Form
2267
2268 finishers:
2269 -
2270 identifier: FlashMessage
2271 options:
2272 messageBody: 'Thx for using TYPO3'
2273 messageTitle: 'Merci'
2274 severity: 0
2275 ...
2276
2277
2278 Usage through code:
2279
2280 .. code-block:: php
2281
2282 $formDefinition->createFinisher('FlashMessage', [
2283 'messageBody' => 'Thx for using TYPO3',
2284 'messageTitle' => 'Merci',
2285 'severity' => \TYPO3\CMS\Core\Messaging\AbstractMessage::OK,
2286 ]);
2287
2288 or create manually (not preferred)
2289
2290 .. code-block:: php
2291
2292 $flashMessageFinisher = $this->objectManager->get(FlashMessageFinisher::class);
2293 $flashMessageFinisher->setOptions([
2294 'messageBody' => 'Thx for using TYPO3',
2295 'messageTitle' => 'Merci',
2296 'severity' => \TYPO3\CMS\Core\Messaging\AbstractMessage::OK,
2297 ]);
2298 $formDefinition->addFinisher($flashMessageFinisher);
2299
2300
2301 .. _apireference-finisheroptions-flashmessagefinisher-options:
2302
2303 Options
2304 ^^^^^^^
2305
2306 .. _apireference-finisheroptions-flashmessagefinisher-options-messagebody:
2307
2308 messageBody
2309 +++++++++++
2310
2311 :aspect:`Data type`
2312 string
2313
2314 :aspect:`Mandatory`
2315 Yes
2316
2317 :aspect:`Default value`
2318 null
2319
2320 :aspect:`Description`
2321 The flash message body
2322
2323
2324 .. _apireference-finisheroptions-flashmessagefinisher-options-messagetitle:
2325
2326 messageTitle
2327 ++++++++++++
2328
2329 :aspect:`Data type`
2330 string
2331
2332 :aspect:`Mandatory`
2333 No
2334
2335 :aspect:`Default value`
2336 empty string
2337
2338 :aspect:`Description`
2339 The flash message title
2340
2341
2342 .. _apireference-finisheroptions-flashmessagefinisher-options-messagearguments:
2343
2344 messageArguments
2345 ++++++++++++++++
2346
2347 :aspect:`Data type`
2348 array
2349
2350 :aspect:`Mandatory`
2351 No
2352
2353 :aspect:`Default value`
2354 empty array
2355
2356 :aspect:`Description`
2357 The flash message arguments, if needed
2358
2359
2360 .. _apireference-finisheroptions-flashmessagefinisher-options-messagecode:
2361
2362 messageCode
2363 +++++++++++
2364
2365 :aspect:`Data type`
2366 int
2367
2368 :aspect:`Mandatory`
2369 No
2370
2371 :aspect:`Default value`
2372 null
2373
2374 :aspect:`Description`
2375 The flash message code, if needed
2376
2377
2378 .. _apireference-finisheroptions-flashmessagefinisher-options-severity:
2379
2380 severity
2381 ++++++++
2382
2383 :aspect:`Data type`
2384 int
2385
2386 :aspect:`Mandatory`
2387 No
2388
2389 :aspect:`Default value`
2390 \TYPO3\CMS\Core\Messaging\AbstractMessage::OK (0)
2391
2392 :aspect:`Description`
2393 The flash message severity code.
2394 See \TYPO3\CMS\Core\Messaging\AbstractMessage constants for the codes.
2395
2396
2397 .. _apireference-finisheroptions-redirectfinisher:
2398
2399 Redirect finisher
2400 -----------------
2401
2402 A simple finisher that redirects to another page.
2403
2404
2405 Usage within form definition
2406
2407 .. code-block:: yaml
2408
2409 identifier: example-form
2410 label: 'example'
2411 type: Form
2412
2413 finishers:
2414 -
2415 identifier: Redirect
2416 options:
2417 pageUid: 1
2418 additionalParameters: 'param1=value1&param2=value2'
2419 ...
2420
2421
2422 Usage through code:
2423
2424 .. code-block:: php
2425
2426 $formDefinition->createFinisher('Redirect', [
2427 'pageUid' => 1,
2428 'additionalParameters' => 'param1=value1&param2=value2',
2429 ]);
2430
2431 or create manually (not preferred)
2432
2433 .. code-block:: php
2434
2435 $redirectFinisher = $this->objectManager->get(RedirectFinisher::class);
2436 $redirectFinisher->setOptions([
2437 'pageUid' => 1,
2438 'additionalParameters' => 'param1=value1&param2=value2',
2439 ]);
2440 $formDefinition->addFinisher($redirectFinisher);
2441
2442
2443 .. _apireference-finisheroptions-redirectfinisher-options:
2444
2445 Options
2446 ^^^^^^^
2447
2448 .. _apireference-finisheroptions-redirectfinisher-options-pageuid:
2449
2450 pageUid
2451 +++++++
2452
2453 :aspect:`Data type`
2454 int
2455
2456 :aspect:`Mandatory`
2457 Yes
2458
2459 :aspect:`Default value`
2460 1
2461
2462 :aspect:`Description`
2463 Redirect to this page uid
2464
2465
2466 .. _apireference-finisheroptions-redirectfinisher-options-additionalparameters:
2467
2468 additionalParameters
2469 ++++++++++++++++++++
2470
2471 :aspect:`Data type`
2472 string
2473
2474 :aspect:`Mandatory`
2475 No
2476
2477 :aspect:`Default value`
2478 empty string
2479
2480 :aspect:`Description`
2481 Additional parameters which should be used on the target page
2482
2483
2484 .. _apireference-finisheroptions-redirectfinisher-options-delay:
2485
2486 delay
2487 +++++
2488
2489 :aspect:`Data type`
2490 int
2491
2492 :aspect:`Mandatory`
2493 No
2494
2495 :aspect:`Default value`
2496 0
2497
2498 :aspect:`Description`
2499 The redirect delay in seconds.
2500
2501
2502 .. _apireference-finisheroptions-redirectfinisher-options-statuscode:
2503
2504 statusCode
2505 ++++++++++
2506
2507 :aspect:`Data type`
2508 int
2509
2510 :aspect:`Mandatory`
2511 No
2512
2513 :aspect:`Default value`
2514 303
2515
2516 :aspect:`Description`
2517 The HTTP status code for the redirect. Default is "303 See Other".
2518
2519
2520 .. _apireference-finisheroptions-savetodatabasefinisher:
2521
2522 SaveToDatabase finisher
2523 -----------------------
2524
2525 This finisher saves the data from a submitted form into a database table.
2526
2527
2528 Usage within form definition
2529
2530 .. code-block:: yaml
2531
2532 identifier: example-form
2533 label: 'example'
2534 type: Form
2535
2536 finishers:
2537 -
2538 identifier: SaveToDatabase
2539 options:
2540 table: 'fe_users'
2541 mode: update
2542 whereClause:
2543 uid: 1
2544 databaseColumnMappings:
2545 pid:
2546 value: 1
2547 elements:
2548 textfield-identifier-1:
2549 mapOnDatabaseColumn: 'first_name'
2550 textfield-identifier-2:
2551 mapOnDatabaseColumn: 'last_name'
2552 textfield-identifier-3:
2553 mapOnDatabaseColumn: 'username'
2554 advancedpassword-1:
2555 mapOnDatabaseColumn: 'password'
2556 skipIfValueIsEmpty: true
2557 ...
2558
2559
2560 Usage through code:
2561
2562 .. code-block:: php
2563
2564 $formDefinition->createFinisher('SaveToDatabase', [
2565 'table' => 'fe_users',
2566 'mode' => 'update',
2567 'whereClause' => [
2568 'uid' => 1,
2569 ],
2570 'databaseColumnMappings' => [
2571 'pid' => ['value' => 1],
2572 ],
2573 'elements' => [
2574 'textfield-identifier-1' => ['mapOnDatabaseColumn' => 'first_name'],
2575 'textfield-identifier-2' => ['mapOnDatabaseColumn' => 'last_name'],
2576 'textfield-identifier-3' => ['mapOnDatabaseColumn' => 'username'],
2577 'advancedpassword-1' => [
2578 'mapOnDatabaseColumn' => 'password',
2579 'skipIfValueIsEmpty' => true,
2580 ],
2581 ],
2582 ]);
2583
2584 or create manually (not preferred)
2585
2586 .. code-block:: php
2587
2588 $saveToDatabaseFinisher = $this->objectManager->get(SaveToDatabaseFinisher::class);
2589 $saveToDatabaseFinisher->setOptions([
2590 'table' => 'fe_users',
2591 'mode' => 'update',
2592 'whereClause' => [
2593 'uid' => 1,
2594 ],
2595 'databaseColumnMappings' => [
2596 'pid' => ['value' => 1],
2597 ],
2598 'elements' => [
2599 'textfield-identifier-1' => ['mapOnDatabaseColumn' => 'first_name'],
2600 'textfield-identifier-2' => ['mapOnDatabaseColumn' => 'last_name'],
2601 'textfield-identifier-3' => ['mapOnDatabaseColumn' => 'username'],
2602 'advancedpassword-1' => [
2603 'mapOnDatabaseColumn' => 'password',
2604 'skipIfValueIsEmpty' => true,
2605 ],
2606 ],
2607 ]);
2608 $formDefinition->addFinisher($saveToDatabaseFinisher);
2609
2610 You can write options as an array to perform multiple database operations.
2611
2612 Usage within form definition
2613
2614 .. code-block:: yaml
2615
2616 identifier: example-form
2617 label: 'example'
2618 type: Form
2619
2620 finishers:
2621 -
2622 identifier: SaveToDatabase
2623 options:
2624 1:
2625 table: 'my_table'
2626 mode: insert
2627 databaseColumnMappings:
2628 some_column:
2629 value: 'cool'
2630 2:
2631 table: 'my_other_table'
2632 mode: update
2633 whereClause:
2634 pid: 1
2635 databaseColumnMappings:
2636 some_other_column:
2637 value: '{SaveToDatabase.insertedUids.1}'
2638 ...
2639
2640
2641 Usage through code:
2642
2643 .. code-block:: php
2644
2645 $formDefinition->createFinisher('SaveToDatabase', [
2646 1 => [
2647 'table' => 'my_table',
2648 'mode' => 'insert',
2649 'databaseColumnMappings' => [
2650 'some_column' => ['value' => 'cool'],
2651 ],
2652 ],
2653 2 => [
2654 'table' => 'my_other_table',
2655 'mode' => 'update',
2656 'whereClause' => [
2657 'pid' => 1,
2658 ],
2659 'databaseColumnMappings' => [
2660 'some_other_column' => ['value' => '{SaveToDatabase.insertedUids.1}'],
2661 ],
2662 ],
2663 ]);
2664
2665 or create manually (not preferred)
2666
2667 .. code-block:: php
2668
2669 $saveToDatabaseFinisher = $this->objectManager->get(SaveToDatabaseFinisher::class);
2670 $saveToDatabaseFinisher->setOptions([
2671 1 => [
2672 'table' => 'my_table',
2673 'mode' => 'insert',
2674 'databaseColumnMappings' => [
2675 'some_column' => ['value' => 'cool'],
2676 ],
2677 ],
2678 2 => [
2679 'table' => 'my_other_table',
2680 'mode' => 'update',
2681 'whereClause' => [
2682 'pid' => 1,
2683 ],
2684 'databaseColumnMappings' => [
2685 'some_other_column' => ['value' => '{SaveToDatabase.insertedUids.1}'],
2686 ],
2687 ],
2688 ]);
2689 $formDefinition->addFinisher($saveToDatabaseFinisher);
2690
2691
2692 This perform 2 database operations.
2693 One insert and one update.
2694 You can access the inserted uids through '{SaveToDatabase.insertedUids.<theArrayKeyNumberWithinOptions>}'
2695 If you perform a insert operation, the value of the inserted database row will be stored within the FinisherVariableProvider.
2696 <theArrayKeyNumberWithinOptions> references to the numeric options.* key.
2697
2698
2699 .. _apireference-finisheroptions-savetodatabasefinisher-options:
2700
2701 Options
2702 ^^^^^^^
2703
2704 .. _apireference-finisheroptions-savetodatabasefinisher-options-table:
2705
2706 table
2707 +++++
2708
2709 :aspect:`Data type`
2710 string
2711
2712 :aspect:`Mandatory`
2713 Yes
2714
2715 :aspect:`Default value`
2716 null
2717
2718 :aspect:`Description`
2719 Insert or update values into this table.
2720
2721
2722 .. _apireference-finisheroptions-savetodatabasefinisher-options-mode:
2723
2724 mode
2725 ++++
2726
2727 :aspect:`Data type`
2728 string
2729
2730 :aspect:`Mandatory`
2731 No
2732
2733 :aspect:`Default value`
2734 'insert'
2735
2736 :aspect:`Possible values`
2737 insert/ update
2738
2739 :aspect:`Description`
2740 ``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
2741
2742 ``update`` will update a given database row with the values from the submitted form and/or some predefined values. 'options.whereClause' is then required.
2743
2744
2745 .. _apireference-finisheroptions-savetodatabasefinisher-options-whereclause:
2746
2747 whereClause
2748 +++++++++++
2749
2750 :aspect:`Data type`
2751 array
2752
2753 :aspect:`Mandatory`
2754 Yes, if mode = update
2755
2756 :aspect:`Default value`
2757 empty array
2758
2759 :aspect:`Description`
2760 This where clause will be used for a database update action
2761
2762
2763 .. _apireference-finisheroptions-savetodatabasefinisher-options-elements:
2764
2765 elements
2766 ++++++++
2767
2768 :aspect:`Data type`
2769 array
2770
2771 :aspect:`Mandatory`
2772 Yes
2773
2774 :aspect:`Default value`
2775 empty array
2776
2777 :aspect:`Description`
2778 Use ``options.elements`` to map form element values to existing database columns.
2779 Each key within ``options.elements`` has to match with a form element identifier.
2780 The value for each key within ``options.elements`` is an array with additional informations.
2781
2782
2783 .. _apireference-finisheroptions-savetodatabasefinisher-options-elements-<formelementidentifier>-mapondatabasecolumn:
2784
2785 elements.<formElementIdentifier>.mapOnDatabaseColumn
2786 ++++++++++++++++++++++++++++++++++++++++++++++++++++
2787
2788 :aspect:`Data type`
2789 string
2790
2791 :aspect:`Mandatory`
2792 Yes
2793
2794 :aspect:`Default value`
2795 undefined
2796
2797 :aspect:`Description`
2798 The value from the submitted form element with the identifier ``<formElementIdentifier>`` will be written into this database column.
2799
2800
2801 .. _apireference-finisheroptions-savetodatabasefinisher-options-elements-<formelementidentifier>-skipifvalueisempty:
2802
2803 elements.<formElementIdentifier>.skipIfValueIsEmpty
2804 +++++++++++++++++++++++++++++++++++++++++++++++++++
2805
2806 :aspect:`Data type`
2807 bool
2808
2809 :aspect:`Mandatory`
2810 No
2811
2812 :aspect:`Default value`
2813 false
2814
2815 :aspect:`Description`
2816 Set this to true if the database column should not be written if the value from the submitted form element with the identifier
2817 ``<formElementIdentifier>`` is empty (think about password fields etc.)
2818
2819
2820 .. _apireference-finisheroptions-savetodatabasefinisher-options-elements-<formelementidentifier>-savefileidentifierinsteadofuid:
2821
2822 elements.<formElementIdentifier>.saveFileIdentifierInsteadOfUid
2823 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2824
2825 :aspect:`Data type`
2826 bool
2827
2828 :aspect:`Mandatory`
2829 No
2830
2831 :aspect:`Default value`
2832 false
2833
2834 :aspect:`Description`
2835 Set this to true if the database column should not be written if the value from the submitted form element with the identifier
2836 ``<formElementIdentifier>`` is empty (think about password fields etc.)
2837
2838 This setting only rules for form elements which creates a FAL object like ``FileUpload`` or ``ImageUpload``.
2839 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
2840 FAL identifier (1:/user_uploads/some_uploaded_pic.jpg) instead.
2841
2842
2843 .. _apireference-finisheroptions-savetodatabasefinisher-options-databasecolumnmappings:
2844
2845 databaseColumnMappings
2846 ++++++++++++++++++++++
2847
2848 :aspect:`Data type`
2849 array
2850
2851 :aspect:`Mandatory`
2852 No
2853
2854 :aspect:`Default value`
2855 empty array
2856
2857 :aspect:`Description`
2858 Use this to map database columns to static values.
2859 Each key within ``options.databaseColumnMappings`` has to match with an existing database column.
2860 The value for each key within ``options.databaseColumnMappings`` is an array with additional informations.
2861
2862 This mapping is done *before* the ``options.element`` mapping.
2863 This means if you map a database column to a value through ``options.databaseColumnMappings`` and map a submitted
2864 form element value to the same database column through ``options.element``, the submitted form element value
2865 will override the value you set within ``options.databaseColumnMappings``.
2866
2867
2868 .. _apireference-finisheroptions-savetodatabasefinisher-options-databasecolumnmappings.<databasecolumnname>.value:
2869
2870 databaseColumnMappings.<databaseColumnName>.value
2871 +++++++++++++++++++++++++++++++++++++++++++++++++
2872
2873 :aspect:`Data type`
2874 string
2875
2876 :aspect:`Mandatory`
2877 Yes
2878
2879 :aspect:`Default value`
2880 undefined
2881
2882 :aspect:`Description`
2883 The value which will be written to the database column.
2884 You can also use the :ref:`FormRuntime accessor feature<concepts-frontendrendering-codecomponents-customfinisherimplementations-accessingoptions-formruntimeaccessor>` to access every getable property from the ``FormRuntime``
2885 In short: use something like ``{<formElementIdentifier>}`` to get the value from the submitted form element with the identifier ``<formElementIdentifier>``.
2886
2887 If you use the FormRuntime accessor feature within ``options.databaseColumnMappings``, the functionality is nearly identical
2888 to the ``options.elements`` configuration variant.
2889
2890
2891 .. _apireference-finisheroptions-savetodatabasefinisher-options-databasecolumnmappings.<databasecolumnname>.skipifvalueisempty:
2892
2893 databaseColumnMappings.<databaseColumnName>.skipIfValueIsEmpty
2894 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2895
2896 :aspect:`Data type`
2897 bool
2898
2899 :aspect:`Mandatory`
2900 No
2901
2902 :aspect:`Default value`
2903 false
2904
2905 :aspect:`Description`
2906 Set this to true if the database column should not be written if the value from ``options.databaseColumnMappings.<databaseColumnName>.value`` is empty.
2907
2908
2909
2910 .. _apireference-formeditor:
2911
2912 Form editor
2913 ===========
2914
2915
2916 .. _apireference-formeditor-hooks:
2917
2918 Hooks
2919 -----
2920
2921 EXT:form implements various hooks so that forms can be manipulated while being
2922 created or saved.
2923
2924
2925 .. _apireference-formeditor-hooks-beforeformcreate:
2926
2927 beforeFormCreate
2928 ^^^^^^^^^^^^^^^^
2929
2930 The form manager calls the 'beforeFormCreate' hook.
2931
2932
2933 .. _apireference-formeditor-hooks-beforeformcreate-connect:
2934
2935 Connect to the hook
2936 +++++++++++++++++++
2937
2938 .. code-block:: php
2939
2940 $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['beforeFormCreate'][<useATimestampAsKeyPlease>]
2941 = \VENDOR\YourNamespace\YourClass::class;
2942
2943
2944 .. _apireference-formeditor-hooks-beforeformcreate-use:
2945
2946 Use the hook
2947 ++++++++++++
2948
2949 .. code-block:: php
2950
2951 /**
2952 * @param string $formPersistenceIdentifier
2953 * @param array $formDefinition
2954 * @return array
2955 */
2956 public function beforeFormCreate(string $formPersistenceIdentifier, array $formDefinition): array
2957 {
2958 return $formDefinition;
2959 }
2960
2961
2962 .. _apireference-formeditor-hooks-beforeformduplicate:
2963
2964 beforeFormDuplicate
2965 ^^^^^^^^^^^^^^^^^^^
2966
2967 The form manager call the 'beforeFormDuplicate' hook.
2968
2969
2970 .. _apireference-formeditor-hooks-beforeformduplicate-connect:
2971
2972 Connect to the hook
2973 +++++++++++++++++++
2974
2975 .. code-block:: php
2976
2977 $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['beforeFormDuplicate'][<useATimestampAsKeyPlease>]
2978 = \VENDOR\YourNamespace\YourClass::class;
2979
2980
2981 .. _apireference-formeditor-hooks-beforeformduplicate-use:
2982
2983 Use the hook
2984 ++++++++++++
2985
2986 .. code-block:: php
2987
2988 /**
2989 * @param string $formPersistenceIdentifier
2990 * @param array $formDefinition
2991 * @return array
2992 */
2993 public function beforeFormDuplicate(string $formPersistenceIdentifier, array $formDefinition): array
2994 {
2995 return $formDefinition;
2996 }
2997
2998
2999 .. _apireference-formeditor-hooks-beforeformdelete:
3000
3001 beforeFormDelete
3002 ^^^^^^^^^^^^^^^^
3003
3004 The form manager call the 'beforeFormDelete' hook.
3005
3006
3007 .. _apireference-formeditor-hooks-beforeformdelete-connect:
3008
3009 Connect to the hook
3010 +++++++++++++++++++
3011
3012 .. code-block:: php
3013
3014 $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['beforeFormDelete'][<useATimestampAsKeyPlease>]
3015 = \VENDOR\YourNamespace\YourClass::class;
3016
3017
3018 .. _apireference-formeditor-hooks-beforeformdelete-use:
3019
3020 Use the hook
3021 ++++++++++++
3022
3023 .. code-block:: php
3024
3025 /**
3026 * @param string $formPersistenceIdentifier
3027 * @return void
3028 */
3029 public function beforeFormDelete(string $formPersistenceIdentifier)
3030 {
3031 }
3032
3033
3034 .. _apireference-formeditor-hooks-beforeformsave:
3035
3036 beforeFormSave
3037 ^^^^^^^^^^^^^^
3038
3039 The form editor call the 'beforeFormSave' hook.
3040
3041
3042 .. _apireference-formeditor-hooks-beforeformsave-connect:
3043
3044 Connect to the hook
3045 +++++++++++++++++++
3046
3047 .. code-block:: php
3048
3049 $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['beforeFormSave'][<useATimestampAsKeyPlease>]
3050 = \VENDOR\YourNamespace\YourClass::class;
3051
3052
3053 .. _apireference-formeditor-hooks-beforeformsave-use:
3054
3055 Use the hook
3056 ++++++++++++
3057
3058 .. code-block:: php
3059
3060 /**
3061 * @param string $formPersistenceIdentifier
3062 * @param array $formDefinition
3063 * @return array
3064 */
3065 public function beforeFormSave(string $formPersistenceIdentifier, array $formDefinition): array
3066 {
3067 return $formDefinition;
3068 }
3069
3070
3071
3072 .. _apireference-formeditor-stage:
3073
3074 Stage
3075 -----
3076
3077
3078 .. _apireference-formeditor-stage-commonabstractformelementtemplates:
3079
3080 Common abstract view form element templates
3081 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3082
3083 The basic idea of the ``abstract view`` is to give a quick overview of the
3084 configuration of form elements, without having to click them in order to view
3085 the detailed configuration in the ``Inspector``. The ``form editor`` requires
3086 for each form element an inline HTML template and the corresponding JavaScript
3087 code. Information matching inline HTML templates to the appropriate form
3088 elements must be configured within :ref:`TYPO3.CMS.Form.prototypes.\<prototypeIdentifier>.formeditor.formEditorPartials <typo3.cms.form.prototypes.\<prototypeidentifier>.formeditor.formeditorpartials>`.
3089 At this point, the key identifying the form element follows a convention:
3090 ``FormElement-<formElementTypeIdentifier>``. The value for the key tells the
3091 ``form editor`` which inline HTML template should be loaded for the respective
3092 form element. This template is then cloned via JavaScript, brought to life
3093 using the form element configuration and shown in the ``Stage`` component.
3094
3095 You can read about how particular form elements are mapped to inline HTML
3096 templates and how the corresponding JavaScript code are executed :ref:`here <apireference-formeditor-basicjavascriptconcepts-events-view-stage-abstract-render-template-perform>`.
3097
3098 The form element inline HTML templates and the corresponding JavaScript code
3099 are configured for reuse. In this way, most form elements you create should be
3100 able to access the components delivered in EXT:form, without requiring separate
3101 implementations (at least we hope so). For your own implementations, study
3102 EXT:form stage templates, which is found under ``Resources/Private/Backend/Partials/FormEditor/Stage/*``.
3103 The corresponding JavaScript code is found under ``Resources/Public/JavaScript/Backend/FormEditor/StageComponent.js``.
3104 The method ``_renderTemplateDispatcher()`` shows, which methods will be used to
3105 render the respective form elements.
3106
3107 Essentially, two different inline HTML templates exists that can be rendered
3108 with two different JavaScript methods, which are described below. The other
3109 inline HTML templates are almost all versions of these two basic variants and
3110 show extra/ other form-element information. The same applies to the
3111 corresponding JavaScript codes.
3112
3113
3114 .. _apireference-formeditor-stage-commonabstractformelementtemplates-simpletemplate:
3115
3116 Stage/SimpleTemplate
3117 ++++++++++++++++++++
3118
3119 This template displays the ``label`` property of the form element. Depending on
3120 the JavaScript rendering method used, a validator icon will be shown on the
3121 right as soon as a validator is added to the form element. In this case, the
3122 used validator labels are likewise displayed, if the form element is selected
3123 and/ or the cursor hovers over the form element. This template should generally
3124 be enough for all possible, self-defined form elements.
3125
3126 The ``Stage/SimpleTemplate`` can then :ref:`be rendered <apireference-formeditor-basicjavascriptconcepts-events-view-stage-abstract-render-template-perform>`
3127 with the method ``getFormEditorApp().getViewModel().getStage().renderSimpleTemplateWithValidators()``.
3128
3129
3130 .. _apireference-formeditor-stage-commonabstractformelementtemplates-selecttemplate:
3131
3132 Stage/SelectTemplate
3133 ++++++++++++++++++++
3134
3135 This template behaves like the ``Stage/SimpleTemplate`` except that it also
3136 shows the chosen options labels of the form elements. This is naturally only
3137 possible for form elements that have ``properties.options.*`` values, e.g.
3138 ``MultiCheckbox``:
3139
3140 .. code-block:: yaml
3141
3142 type: MultiCheckbox
3143 identifier: multicheckbox-1
3144 label: 'Multi checkbox'
3145 properties:
3146 options:
3147 value1: label1
3148 value2: label2
3149
3150
3151 The template will now list 'label1' and 'label2'.
3152
3153 You can copy this template variant for your own form element, if that form-
3154 element template also lists array values, which, however, are not found under
3155 ``properties.options.*``. For this purpose, the 'Stage/FileUploadTemplate' is
3156 an example. It is basically the 'Stage/SelectTemplate' template, with one
3157 altered property.
3158
3159 In the ``FileUpload`` form element, multiple property values are available
3160 under ``properties.allowedMimeTypes.*`` as an array.
3161
3162 .. code-block:: yaml
3163
3164 type: FileUpload
3165 identifier: fileupload-1
3166 label: 'File upload'
3167 properties:
3168 saveToFileMount: '1:/user_upload/'
3169 allowedMimeTypes:
3170 - application/msexcel
3171 - application/pdf
3172
3173
3174 Stage/SelectTemplate
3175
3176 .. code-block:: html
3177
3178 <div data-identifier="multiValueContainer" data-template-property="properties.options">
3179
3180
3181 Stage/FileUploadTemplate
3182
3183 .. code-block:: html
3184
3185 <div data-identifier="multiValueContainer" data-template-property="properties.allowedMimeTypes">
3186
3187
3188 ``data-template-property`` contains the path to the property, which is to be
3189 read out of the form element and then shown in the template.
3190
3191 The ``Stage/SelectTemplate`` can then :ref:`be rendered <apireference-formeditor-basicjavascriptconcepts-events-view-stage-abstract-render-template-perform>`
3192 with the method ``getFormEditorApp().getViewModel().getStage().renderSelectTemplates()``.
3193
3194
3195
3196 .. _apireference-formeditor-basicjavascriptconcepts:
3197
3198 Basic JavaScript Concepts
3199 -------------------------
3200
3201
3202 .. _apireference-formeditor-basicjavascriptconcepts-events:
3203
3204 Events
3205 ^^^^^^
3206
3207 EXT:form implements the ``publish/subscribe pattern`` to put the event handling
3208 into effect. To learn more about this pattern, you should read
3209 https://addyosmani.com/resources/essentialjsdesignpatterns/book/.
3210 Note that the order of the subscriber is not manipulable and that information
3211 flow between the subscribers does not exist. All events must be asynchronously
3212 designed.
3213
3214
3215 Publish an event:
3216
3217 .. code-block:: javascript
3218
3219 getPublisherSubscriber().publish('eventname', [argumentToPublish1, argumentToPublish2, ...]);
3220
3221
3222 Subscribe to an event:
3223
3224 .. code-block:: javascript
3225
3226 var subscriberToken = getPublisherSubscriber().subscribe('eventname', function(topic, args) {
3227 // args[0] = argumentToPublish1
3228 // args[1] = argumentToPublish2
3229 // ...
3230 });
3231
3232
3233 Unsubscribe an event subscriber:
3234
3235 .. code-block:: javascript
3236
3237 getPublisherSubscriber().unsubscribe(subscriberToken);
3238
3239
3240 EXT:form itself publishes and subscribes to the following events:
3241
3242 .. _apireference-formeditor-basicjavascriptconcepts-events-ajax-beforesend:
3243
3244 ajax/beforeSend
3245 +++++++++++++++
3246
3247 Each Ajax request is called before this event is sent. EXT:form uses this event
3248 to display the spinner icon on the save button.
3249
3250
3251 Subscribe to the event:
3252
3253 .. code-block:: javascript
3254
3255 /**
3256 * @private
3257 *
3258 * @param string
3259 * @param array
3260 * @return void
3261 */
3262 getPublisherSubscriber().subscribe('ajax/beforeSend', function(topic, args) {
3263 });
3264
3265
3266 .. _apireference-formeditor-basicjavascriptconcepts-events-ajax-complete:
3267
3268 ajax/complete
3269 +++++++++++++
3270
3271 Each Ajax request is called after the end of this event. EXT:form uses this
3272 event to remove the spinner icon on the save button.
3273
3274
3275 Subscribe to the event:
3276
3277 .. code-block:: javascript
3278
3279 /**
3280 * @private
3281 *
3282 * @param string
3283 * @param array
3284 * @return void
3285 */
3286 getPublisherSubscriber().subscribe('ajax/complete', function(topic, args) {
3287 });
3288
3289
3290 .. _apireference-formeditor-basicjavascriptconcepts-events-core-ajax-error:
3291
3292 core/ajax/error
3293 +++++++++++++++
3294
3295 This event is called if the Ajax request, which is used to save the form or to
3296 render the current page of the form in the ``preview view``, fails. EXT:form
3297 uses this event to show an error message as a flash message and to show the
3298 received error text in the ``preview view``.
3299
3300
3301 Subscribe to the event:
3302
3303 .. code-block:: javascript
3304
3305 /**
3306 * @private
3307 *
3308 * @param string
3309 * @param array
3310 * args[0] = jqXHR
3311 * args[1] = textStatus
3312 * args[2] = errorThrown
3313 * @return void
3314 */
3315 getPublisherSubscriber().subscribe('core/ajax/error', function(topic, args) {
3316 });
3317
3318
3319 .. _apireference-formeditor-basicjavascriptconcepts-events-core-ajax-renderformdefinitionpage-success:
3320
3321 core/ajax/renderFormDefinitionPage/success
3322 ++++++++++++++++++++++++++++++++++++++++++
3323
3324 This event is called if the Ajax request that is used to render the current
3325 page of the form in the ``preview view`` was successful. EXT:form uses this
3326 event to display the rendered form in the ``preview view``.
3327
3328
3329 Subscribe to the event:
3330
3331 .. code-block:: javascript
3332
3333 /**
3334 * @private
3335 *
3336 * @param string
3337 * @param array
3338 * args[0] = html
3339 * args[1] = pageIndex
3340 * @return void
3341 */
3342 getPublisherSubscriber().subscribe('core/ajax/renderFormDefinitionPage/success', function(topic, args) {
3343 });
3344
3345
3346 .. _apireference-formeditor-basicjavascriptconcepts-events-core-ajax-saveformdefinition-success:
3347
3348 core/ajax/saveFormDefinition/success
3349 ++++++++++++++++++++++++++++++++++++
3350
3351 This event is called if the Ajax request that is used to save the form was
3352 successful. EXT:form uses this event to display a success message as a flash
3353 message. The ``form editor`` is also informed that no unsaved content currently
3354 exists.
3355
3356
3357 Subscribe to the event:
3358
3359 .. code-block:: javascript
3360
3361 /**
3362 * @private
3363 *
3364 * @param string
3365 * @param array
3366 * args[0] = html
3367 * @return void
3368 */
3369 getPublisherSubscriber().subscribe('core/ajax/saveFormDefinition/success', function(topic, args) {
3370 });
3371
3372
3373 .. _apireference-formeditor-basicjavascriptconcepts-events-core-applicationstate-add:
3374
3375 core/applicationState/add
3376 +++++++++++++++++++++++++
3377
3378 The addition/ deletion and movement of form elements und property collection
3379 elements (validators/ finishers) is saved in an internal stack so that the
3380 undo/ redo function can be implemented. This event is called whenever the
3381 current state is added to the stack. EXT:form uses this event to reset the
3382 enabled/ disabled state of the undo/ redo buttons.
3383
3384
3385 Subscribe to the event:
3386
3387 .. code-block:: javascript
3388
3389 /**
3390 * @private
3391 *
3392 * @param string
3393 * @param array
3394 * args[0] = applicationState
3395 * args[1] = stackPointer
3396 * args[2] = stackSize
3397 * @return void
3398 */
3399 getPublisherSubscriber().subscribe('core/applicationState/add', function(topic, args) {
3400 });
3401
3402
3403 .. _apireference-formeditor-basicjavascriptconcepts-events-core-currentlyselectedformelementchanged:
3404
3405 core/currentlySelectedFormElementChanged
3406 ++++++++++++++++++++++++++++++++++++++++
3407
3408 The method ``getFormEditorApp().setCurrentlySelectedFormElement()`` tells the
3409 ``form editor`` which form element should currently be dealt with. This method
3410 calls this event at the end.
3411
3412
3413 Subscribe to the event:
3414
3415 .. code-block:: javascript
3416
3417 /**
3418 * @private
3419 *
3420 * @param string
3421 * @param array
3422 * args[0] = formElement
3423 * @return void
3424 */
3425 getPublisherSubscriber().subscribe('core/currentlySelectedFormElementChanged', function(topic, args) {
3426 });
3427
3428
3429 .. _apireference-formeditor-basicjavascriptconcepts-events-core-formelement-somepropertychanged:
3430
3431 core/formElement/somePropertyChanged
3432 ++++++++++++++++++++++++++++++++++++
3433
3434 Each :ref:`FormElement model<apireference-formeditor-basicjavascriptconcepts-formelementmodel>`
3435 can write properties into the ``FormElement model`` through the methods ``get``
3436 and ``set``. Each property path can register an event name for the publisher
3437 through the method ``on``. This event is then always called when a property
3438 path is written via ``set``. Read :ref:`FormElement model<concepts-formeditor-basicjavascriptconcepts-formelementmodel>`
3439 for more information. EXT:form automatically registers for all known property
3440 paths of a form element the event ``core/formElement/somePropertyChanged``.
3441 This means that every property written via ``set`` calls this event. Among
3442 other things, EXT:form uses this event for, for example, updating the label of
3443 a form element in other components (e.g. ``Tree`` component ) when this label
3444 is changed. Furthermore, any validation errors from form element properties
3445 are indicated by this event in the ``Tree`` component.
3446
3447
3448 Subscribe to the event:
3449
3450 .. code-block:: javascript
3451
3452 /**
3453 * @private
3454 *
3455 * @param string
3456 * @param array
3457 * args[0] = propertyPath
3458 * args[1] = value
3459 * args[2] = oldValue
3460 * args[3] = formElementIdentifierPath
3461 * @return void
3462 */
3463 getPublisherSubscriber().subscribe('core/formElement/somePropertyChanged', function(topic, args) {
3464 });
3465
3466
3467 .. _apireference-formeditor-basicjavascriptconcepts-events-view-collectionelement-moved:
3468
3469 view/collectionElement/moved
3470 ++++++++++++++++++++++++++++
3471
3472 The method ``getFormEditorApp().getViewModel().movePropertyCollectionElement()``
3473 calls this event at the end. EXT:form uses this event to re-render the
3474 ``Inspector`` component as soon as a property collection element (validator/
3475 finisher) is moved.
3476
3477
3478 Subscribe to the event:
3479
3480 .. code-block:: javascript
3481
3482 /**
3483 * @private
3484 *
3485 * @param string
3486 * @param array
3487 * args[0] = movedCollectionElementIdentifier
3488 * args[1] = previousCollectionElementIdentifier
3489 * args[2] = nextCollectionElementIdentifier
3490 * args[3] = collectionName
3491 * @return void
3492 */
3493 getPublisherSubscriber().subscribe('view/collectionElement/moved', function(topic, args) {
3494 });
3495
3496
3497 .. _apireference-formeditor-basicjavascriptconcepts-events-view-collectionelement-new-added:
3498
3499 view/collectionElement/new/added
3500 ++++++++++++++++++++++++++++++++
3501
3502 The method ``getFormEditorApp().getViewModel().createAndAddPropertyCollectionElement()``
3503 calls this event at the end. EXT:form uses this event to re-render the
3504 ``Inspector`` component as soon as a property collection element (validator/
3505 finisher) is created and added.
3506
3507
3508 Subscribe to the event:
3509
3510 .. code-block:: javascript
3511
3512 /**
3513 * @private
3514 *
3515 * @param string
3516 * @param array
3517 * args[0] = collectionElementIdentifier
3518 * args[1] = collectionName
3519 * args[2] = formElement
3520 * args[3] = collectionElementConfiguration
3521 * args[4] = referenceCollectionElementIdentifier
3522 * @return void
3523 */
3524 getPublisherSubscriber().subscribe('view/collectionElement/new/added', function(topic, args) {
3525 });
3526
3527
3528 .. _apireference-formeditor-basicjavascriptconcepts-events-view-collectionelement-removed:
3529
3530 view/collectionElement/removed
3531 ++++++++++++++++++++++++++++++
3532
3533 The method ``getFormEditorApp().getViewModel().removePropertyCollectionElement()``
3534 calls this event at the end. EXT:form uses this event to re-render the
3535 ``Inspector`` component as soon as a property collection element (validator/
3536 finisher) is removed.
3537
3538
3539 Subscribe to the event:
3540
3541 .. code-block:: javascript
3542
3543 /**
3544 * @private
3545 *
3546 * @param string
3547 * @param array
3548 * args[0] = collectionElementIdentifier
3549 * args[1] = collectionName
3550 * args[2] = formElement
3551 * @return void
3552 */
3553 getPublisherSubscriber().subscribe('view/collectionElement/removed', function(topic, args) {
3554 });
3555
3556
3557 .. _apireference-formeditor-basicjavascriptconcepts-events-view-formelement-inserted:
3558
3559 view/formElement/inserted
3560 +++++++++++++++++++++++++
3561
3562 The method ``getFormEditorApp().getViewModel().createAndAddFormElement()`` and
3563 the event :ref:`view/insertElements/perform/after<apireference-formeditor-basicjavascriptconcepts-events-view-insertelements-perform-after>`
3564 call this event at the end. EXT:form uses this event to set the current
3565 to-be-processed form element (``getFormEditorApp().setCurrentlySelectedFormElement()``)
3566 and to re-render the ``Tree``, ``Stage`` and ``Inspector`` components.
3567
3568
3569 Subscribe to the event:
3570
3571 .. code-block:: javascript
3572
3573 /**
3574 * @private
3575 *
3576 * @param string
3577 * @param array
3578 * args[0] = newFormElement
3579 * @return void
3580 */
3581 getPublisherSubscriber().subscribe('view/formElement/inserted', function(topic, args) {
3582 });
3583
3584
3585 .. _apireference-formeditor-basicjavascriptconcepts-events-view-formelement-moved:
3586
3587 view/formElement/moved
3588 ++++++++++++++++++++++
3589
3590 The method ``getFormEditorApp().getViewModel().moveFormElement()`` calls this
3591 event at the end.
3592
3593
3594 Subscribe to the event:
3595
3596 .. code-block:: javascript
3597
3598 /**
3599 * @private
3600 *
3601 * @param string
3602 * @param array
3603 * args[0] = movedFormElement
3604 * @return void
3605 */
3606 getPublisherSubscriber().subscribe('view/formElement/moved', function(topic, args) {
3607 });
3608
3609
3610 .. _apireference-formeditor-basicjavascriptconcepts-events-view-formelement-removed:
3611
3612 view/formElement/removed
3613 ++++++++++++++++++++++++
3614
3615 The method ``getFormEditorApp().getViewModel().removeFormElement()`` calls this
3616 event at the end. EXT:form uses this event to set the current to-be-processed
3617 form element (``getFormEditorApp().setCurrentlySelectedFormElement()``) and to
3618 re-render the ``Tree``, ``Stage`` and ``Inspector`` components.
3619
3620
3621 Subscribe to the event:
3622
3623 .. code-block:: javascript
3624
3625 /**
3626 * @private
3627 *
3628 * @param string
3629 * @param array
3630 * args[0] = parentFormElement
3631 * @return void
3632 */
3633 getPublisherSubscriber().subscribe('view/formElement/removed', function(topic, args) {
3634 });
3635
3636
3637 .. _apireference-formeditor-basicjavascriptconcepts-events-view-header-button-close-clicked:
3638
3639 view/header/button/close/clicked
3640 ++++++++++++++++++++++++++++++++
3641
3642 The onClick event of the "Close" button in the ``form editor's`` header section
3643 calls this event. EXT:form uses this event to display a warning message in case
3644 there are unsaved changes.
3645
3646
3647 Subscribe to the event:
3648
3649 .. code-block:: javascript
3650
3651 /**
3652 * @private
3653 *
3654 * @param string
3655 * @param array
3656 * @return void
3657 */
3658 getPublisherSubscriber().subscribe('view/header/button/close/clicked', function(topic, args) {
3659 });
3660
3661
3662 .. _apireference-formeditor-basicjavascriptconcepts-events-view-header-button-newpage-clicked:
3663
3664 view/header/button/newPage/clicked
3665 ++++++++++++++++++++++++++++++++++
3666
3667 The onClick event of the "new page" button in the ``form editor's`` header
3668 section calls this event. EXT:form uses this event to display the "new page"
3669 dialog box.
3670
3671
3672 Subscribe to the event:
3673
3674 .. code-block:: javascript
3675
3676 /**
3677 * @private
3678 *
3679 * @param string
3680 * @param array
3681 * args[0] = targetEvent
3682 * @return void
3683 */
3684 getPublisherSubscriber().subscribe('view/header/button/newPage/clicked', function(topic, args) {
3685 });
3686
3687
3688 .. _apireference-formeditor-basicjavascriptconcepts-events-view-header-button-save-clicked:
3689
3690 view/header/button/save/clicked
3691 +++++++++++++++++++++++++++++++
3692
3693 The onClick event of the "save" button in the ``form editor's`` header section
3694 calls this event. EXT:form uses this event either to display a dialog box with
3695 the element in question (if there are validation errors) or to save the ``form
3696 definition`` (if there are no validation errors).
3697
3698
3699 Subscribe to the event:
3700
3701 .. code-block:: javascript
3702
3703 /**
3704 * @private
3705 *
3706 * @param string
3707 * @param array
3708 * @return void
3709 */
3710 getPublisherSubscriber().subscribe('view/header/button/save/clicked', function(topic, args) {
3711 });
3712
3713
3714 .. _apireference-formeditor-basicjavascriptconcepts-events-view-header-formsettings-clicked:
3715
3716 view/header/formSettings/clicked
3717 ++++++++++++++++++++++++++++++++
3718
3719 The onClick event of the "settings" button in the ``form editor's`` header
3720 section calls this event. EXT:form uses this event to select the root form
3721 element.
3722
3723
3724 Subscribe to the event:
3725
3726 .. code-block:: javascript
3727
3728 /**
3729 * @private
3730 *
3731 * @param string
3732 * @param array
3733 * @return void
3734 */
3735 getPublisherSubscriber().subscribe('view/header/formSettings/clicked', function(topic, args) {
3736 });
3737
3738
3739 .. _apireference-formeditor-basicjavascriptconcepts-events-view-insertelements-perform-after:
3740
3741 view/insertElements/perform/after
3742 +++++++++++++++++++++++++++++++++
3743
3744 This event is called from the "new element" dialog box upon selection of a form
3745 element:
3746
3747 - if "After" in the "Create new element" split button in the form-element toolbar for composite elements (e.g. fieldset) is clicked.
3748 - if the "Create new element" button in the form-element toolbar for non-composite elements is clicked.
3749
3750 EXT:form uses this event to create a new form element (``getFormEditorApp().getViewModel().createAndAddFormElement()``)
3751 and then move (``getFormEditorApp().getViewModel().moveFormElement()``) it
3752 below the currently selected element (sibling). At the end of this event, the
3753 event :ref:`view/formElement/inserted<apireference-formeditor-basicjavascriptconcepts-events-view-formelement-inserted>`
3754 is called. The event ``view/formElement/inserted`` in ``getFormEditorApp().getViewModel().createAndAddFormElement()``
3755 was previously deactivated.
3756
3757
3758 Subscribe to the event:
3759
3760 .. code-block:: javascript
3761
3762 /**
3763 * @private
3764 *
3765 * @param string
3766 * @param array
3767 * args[0] = formElementType
3768 * @return void
3769 */
3770 getPublisherSubscriber().subscribe('view/insertElements/perform/after', function(topic, args) {
3771 });
3772
3773
3774 .. _apireference-formeditor-basicjavascriptconcepts-events-view-insertelements-perform-bottom:
3775
3776 view/insertElements/perform/bottom
3777 ++++++++++++++++++++++++++++++++++
3778
3779 This event is called from the "new element" dialog box upon selection of a form
3780 element:
3781
3782 - if, in the ``abstract view`` mode, the "Create new element" button at the end of the ``Stage`` component is clicked.
3783
3784 EXT:form uses this event to create a new form element (``getFormEditorApp().getViewModel().createAndAddFormElement()``).
3785 This element is always created as the last element of the currently selected
3786 page.
3787
3788
3789 Subscribe to the event:
3790
3791 .. code-block:: javascript
3792
3793 /**
3794 * @private
3795 *
3796 * @param string
3797 * @param array
3798 * args[0] = formElementType
3799 * @return void
3800 */
3801 getPublisherSubscriber().subscribe('view/insertElements/perform/bottom', function(topic, args) {
3802 });
3803
3804
3805 .. _apireference-formeditor-basicjavascriptconcepts-events-view-insertelements-perform-inside:
3806
3807 view/insertElements/perform/inside
3808 ++++++++++++++++++++++++++++++++++
3809
3810 This event is called from the "new element" dialog box upon selection of a form
3811 element:
3812
3813 - if "Inside" in the "Create new element" split button in the form-element toolbar for composite elements (e.g. fieldset) is clicked.
3814
3815 EXT:form uses this event to create a new form element as a child element of the
3816 currently selected element (``getFormEditorApp().getViewModel().createAndAddFormElement()``).
3817
3818
3819 Subscribe to the event:
3820
3821 .. code-block:: javascript
3822
3823 /**
3824 * @private
3825 *
3826 * @param string
3827 * @param array
3828 * args[0] = formElementType
3829 * @return void
3830 */
3831 getPublisherSubscriber().subscribe('view/insertElements/perform/inside', function(topic, args) {
3832 });
3833
3834
3835 .. _apireference-formeditor-basicjavascriptconcepts-events-view-insertpages-perform:
3836
3837 view/insertPages/perform
3838 ++++++++++++++++++++++++
3839
3840 This event is called from the "new element" dialog box upon selection of a page
3841 element:
3842
3843 - if the "Create new page" icon in the header section is clicked.
3844 - if the "Create new page" button in the ``Tree`` component is clicked.
3845
3846 EXT:form uses this event to create a new page after the currently selected page
3847 (``getFormEditorApp().getViewModel().createAndAddFormElement()``).
3848
3849
3850 Subscribe to the event:
3851
3852 .. code-block:: javascript
3853
3854 /**
3855 * @private
3856 *
3857 * @param string
3858 * @param array
3859 * args[0] = formElementType
3860 * @return void
3861 */
3862 getPublisherSubscriber().subscribe('view/insertPages/perform', function(topic, args) {
3863 });
3864
3865
3866 .. _apireference-formeditor-basicjavascriptconcepts-events-view-inspector-collectionelement-existing-selected:
3867
3868 view/inspector/collectionElement/existing/selected
3869 ++++++++++++++++++++++++++++++++++++++++++++++++++
3870
3871 The ``inspector editors`` :ref:`ValidatorsEditor <typo3.cms.form.prototypes.\<prototypeidentifier>.formelementsdefinition.\<formelementtypeidentifier>.formeditor.editors.*.finisherseditor>`
3872 and :ref:`FinishersEditor <typo3.cms.form.prototypes.\<prototypeidentifier>.formelementsdefinition.\<formelementtypeidentifier>.formeditor.editors.*.validatorseditor>`
3873 are used to display the available validators/ finishers for a form element as a
3874 select box. Furthermore, these ``inspector editors`` indicate that in the
3875 ``form definition``, validators/ finishers for the currently selected element
3876 already exist. This occurs through the event ``view/inspector/collectionElement/existing/selected``.
3877 EXT:form uses this event to render these validators/ finishers and their
3878 tentatively configured ``inspector editors`` (``getFormEditorApp().getViewModel().renderInspectorCollectionElementEditors()``).
3879
3880 Subscribe to the event:
3881
3882 .. code-block:: javascript
3883
3884 /**
3885 * @private
3886 *
3887 * @param string
3888 * @param array
3889 * args[0] = collectionElementIdentifier
3890 * args[1] = collectionName
3891 * @return void
3892 */
3893 getPublisherSubscriber().subscribe('view/inspector/collectionElement/existing/selected', function(topic, args) {
3894 });
3895
3896
3897 .. _apireference-formeditor-basicjavascriptconcepts-events-view-inspector-collectionelement-new-selected:
3898
3899 view/inspector/collectionElement/new/selected
3900 +++++++++++++++++++++++++++++++++++++++++++++
3901
3902 The ``inspector editors`` :ref:`ValidatorsEditor <typo3.cms.form.prototypes.\<prototypeidentifier>.formelementsdefinition.\<formelementtypeidentifier>.formeditor.editors.*.finisherseditor>`
3903 and :ref:`FinishersEditor <typo3.cms.form.prototypes.\<prototypeidentifier>.formelementsdefinition.\<formelementtypeidentifier>.formeditor.editors.*.validatorseditor>`
3904 are used to display the available validators/ finishers for a form element as a
3905 select box. The onChange event of the select box then calls this event. In
3906 addition, the ``inspector editor`` :ref:`RequiredValidatorEditor <typo3.cms.form.prototypes.\<prototypeidentifier>.formelementsdefinition.\<formelementtypeidentifier>.formeditor.editors.*.requiredvalidatoreditor>`
3907 calls this event when a checkbox is chosen. EXT:form uses this event to add and
3908 render the validator/ finisher of the ``form definition`` via ``getFormEditorApp().getViewModel().createAndAddPropertyCollectionElement()``.
3909
3910
3911 Subscribe to the event:
3912
3913 .. code-block:: javascript
3914
3915 /**
3916 * @private
3917 *
3918 * @param string
3919 * @param array
3920 * args[0] = collectionElementIdentifier
3921 * args[1] = collectionName
3922 * @return void
3923 */
3924 getPublisherSubscriber().subscribe('view/inspector/collectionElement/new/selected', function(topic, args) {
3925 });
3926
3927
3928 .. _apireference-formeditor-basicjavascriptconcepts-events-view-inspector-collectionelement-dnd-update:
3929
3930 view/inspector/collectionElements/dnd/update
3931 ++++++++++++++++++++++++++++++++++++++++++++
3932
3933 EXT:form uses the jQuery plugin 'jquery.mjs.nestedSortable' for the drag-and-
3934 drop functionality. The 'update' event from 'jquery.mjs.nestedSortable' calls
3935 the ``view/inspector/collectionElements/dnd/update`` event if a property
3936 collection element in the ``Inspector`` component is sorted. EXT:form uses this
3937 event to move the validator/ finisher in the ``form definition`` via the method
3938 ``getFormEditorApp().getViewModel().movePropertyCollectionElement()``.
3939
3940
3941 Subscribe to the event:
3942
3943 .. code-block:: javascript
3944
3945 /**
3946 * @private
3947 *
3948 * @param string
3949 * @param array
3950 * args[0] = movedCollectionElementIdentifier
3951 * args[1] = previousCollectionElementIdentifier
3952 * args[2] = nextCollectionElementIdentifier
3953 * args[3] = collectionName
3954 * @return void
3955 */
3956 getPublisherSubscriber().subscribe('view/inspector/collectionElements/dnd/update', function(topic, args) {
3957 });
3958
3959
3960 .. _apireference-formeditor-basicjavascriptconcepts-events-view-inspector-editor-insert-perform:
3961
3962 view/inspector/editor/insert/perform
3963 ++++++++++++++++++++++++++++++++++++
3964
3965 The methods ``getFormEditorApp().getViewModel().renderInspectorEditors()`` (to
3966 render all ``inspector editors`` for a form element) and ``getFormEditorApp().getViewModel().renderInspectorCollectionElementEditors()``
3967 (to render the ``inspector editors`` for a validator/ finisher) call this event
3968 at the end. Strictly speaking, the ``Inspector`` component in the method
3969 ``_renderEditorDispatcher()`` calls this event.
3970 Each ``inspector editor`` has the property :ref:`templateName <typo3.cms.form.prototypes.\<prototypeidentifier>.formelementsdefinition.\<formelementtypeidentifier>.formeditor.editors.*.templatename>`,
3971 which gives the ``form editor`` two pieces of information. On the one hand the
3972 ``templateName`` must match with a key within the :ref:`TYPO3.CMS.Form.prototypes.\<prototypeIdentifier>.formeditor.formEditorPartials <typo3.cms.form.prototypes.\<prototypeidentifier>.formeditor.formeditorpartials>`.
3973 The ``form editor`` can consequently load a corresponding inline HTML template
3974 for the ``inspector editor``. On the other hand, the ``Inspector`` component
3975 must be told which JavaScript code should be executed for the
3976 ``inspector editor``. For the ``inspector editors`` delivered with EXT:form,
3977 this occurs within the method ``_renderEditorDispatcher()``.
3978 An existing hard-coded list of known ``inspector editors`` determines, by means
3979 of the property ``templateName``, which corresponding JavaScript method should
3980 be executed for the ``inspector editor``. At the end, the event
3981 ``view/inspector/editor/insert/perform`` is called. If you wish to implement
3982 your own ``inspector editor``, you can use this event to execute in
3983 :ref:`your own JavaScript module <concepts-formeditor-basicjavascriptconcepts-registercustomjavascriptmodules>`.
3984 the corresponding JavaScript code, with the help of the property
3985 ``templateName``.
3986
3987
3988 Subscribe to the event:
3989
3990 .. code-block:: javascript
3991
3992 /**
3993 * @private
3994 *
3995 * @param string
3996 * @param array
3997 * args[0] = editorConfiguration
3998 * args[1] = editorHtml
3999 * args[2] = collectionElementIdentifier
4000 * args[3] = collectionName
4001 * @return void
4002 */
4003 getPublisherSubscriber().subscribe('view/inspector/editor/insert/perform', function(topic, args) {
4004 });
4005
4006
4007 A simple example that registers a custom ``inspector editor`` called 'Inspector-MyCustomInspectorEditor' and adds it to text form elements:
4008
4009 .. code-block:: yaml
4010
4011 TYPO3:
4012 CMS:
4013 Form:
4014 prototypes:
4015 standard:
4016 formEditor:
4017 dynamicRequireJsModules:
4018 additionalViewModelModules:
4019 - 'TYPO3/CMS/MySitePackage/Backend/FormEditor/ViewModel'
4020 formEditorFluidConfiguration:
4021 partialRootPaths:
4022 100: 'EXT:my_site_package/Resources/Private/Backend/Partials/FormEditor/'
4023 formEditorPartials:
4024 Inspector-MyCustomInspectorEditor: 'Inspector/MyCustomInspectorEditor'
4025 formElementsDefinition:
4026 Text:
4027 formEditor:
4028 editors:
4029 600:
4030 templateName: 'Inspector-MyCustomInspectorEditor'
4031 ...
4032
4033
4034 .. code-block:: javascript
4035 :emphasize-lines: 107-116
4036
4037 /**
4038 * Module: TYPO3/CMS/MySitePackage/Backend/FormEditor/ViewModel
4039 */
4040 define(['jquery',
4041 'TYPO3/CMS/Form/Backend/FormEditor/Helper'
4042 ], function($, Helper) {
4043 'use strict';
4044
4045 return (function($, Helper) {
4046
4047 /**
4048 * @private
4049 *
4050 * @var object
4051 */
4052 var _formEditorApp = null;
4053
4054 /**
4055 * @private
4056 *
4057 * @return object
4058 */
4059 function getFormEditorApp() {
4060 return _formEditorApp;
4061 };
4062
4063 /**
4064 * @private
4065 *
4066 * @return object
4067 */
4068 function getPublisherSubscriber() {
4069 return getFormEditorApp().getPublisherSubscriber();
4070 };
4071
4072 /**
4073 * @private
4074 *
4075 * @return object
4076 */
4077 function getUtility() {
4078 return getFormEditorApp().getUtility();
4079 };
4080
4081 /**
4082 * @private
4083 *
4084 * @param object
4085 * @return object
4086 */
4087 function getHelper() {
4088 return Helper;
4089 };
4090
4091 /**
4092 * @private
4093 *
4094 * @return object
4095 */
4096 function getCurrentlySelectedFormElement() {
4097 return getFormEditorApp().getCurrentlySelectedFormElement();
4098 };
4099
4100 /**
4101 * @private
4102 *
4103 * @param mixed test
4104 * @param string message
4105 * @param int messageCode
4106 * @return void
4107 */
4108 function assert(test, message, messageCode) {
4109 return getFormEditorApp().assert(test, message, messageCode);
4110 };
4111
4112 /**
4113 * @private
4114 *
4115 * @return void
4116 * @throws 1491643380
4117 */
4118 function _helperSetup() {
4119 assert('function' === $.type(Helper.bootstrap),
4120 'The view model helper does not implement the method "bootstrap"',
4121 1491643380
4122 );
4123 Helper.bootstrap(getFormEditorApp());
4124 };
4125
4126 /**
4127 * @private
4128 *
4129 * @return void
4130 */
4131 function _subscribeEvents() {
4132 /**
4133 * @private
4134 *
4135 * @param string
4136 * @param array
4137 * args[0] = editorConfiguration
4138 * args[1] = editorHtml
4139 * args[2] = collectionElementIdentifier
4140 * args[3] = collectionName
4141 * @return void
4142 */
4143 getPublisherSubscriber().subscribe('view/inspector/editor/insert/perform', function(topic, args) {
4144 if (args[0]['templateName'] === 'Inspector-MyCustomInspectorEditor') {
4145 renderMyCustomInspectorEditor(
4146 args[0],
4147 args[1],
4148 args[2],
4149 args[3]
4150 );
4151 }
4152 });
4153 };
4154
4155 /**
4156 * @private
4157 *
4158 * @param object editorConfiguration
4159 * @param object editorHtml
4160 * @param string collectionElementIdentifier
4161 * @param string collectionName
4162 * @return void
4163 */
4164 function renderMyCustomInspectorEditor(editorConfiguration, editorHtml, collectionElementIdentifier, collectionName) {
4165 // do cool stuff
4166 });
4167
4168 /**
4169 * @public
4170 *
4171 * @param object formEditorApp
4172 * @return void
4173 */
4174 function bootstrap(formEditorApp) {
4175 _formEditorApp = formEditorApp;
4176 _helperSetup();
4177 _subscribeEvents();
4178 };
4179
4180 /**
4181 * Publish the public methods.
4182 * Implements the "Revealing Module Pattern".
4183 */
4184 return {
4185 bootstrap: bootstrap
4186 };
4187 })($, Helper);
4188 });
4189
4190
4191 .. _apireference-formeditor-basicjavascriptconcepts-events-view-inspector-removecollectionelement-perform:
4192
4193 view/inspector/removeCollectionElement/perform
4194 ++++++++++++++++++++++++++++++++++++++++++++++
4195
4196 The ``inspector editor`` :ref:`RequiredValidatorEditor <typo3.cms.form.prototypes.\<prototypeidentifier>.formelementsdefinition.\<formelementtypeidentifier>.formeditor.editors.*.requiredvalidatoreditor>`
4197 calls this event, if the checkbox is deselected. EXT:form uses this event to
4198 remove the configured required validator ('NotEmpty') from the ``form
4199 definition`` through the method ``getFormEditorApp().getViewModel().removePropertyCollectionElement()``.
4200
4201
4202 Subscribe to the event:
4203
4204 .. code-block:: javascript
4205
4206 /**
4207 * @private
4208 *
4209 * @param string
4210 * @param array
4211 * args[0] = collectionElementIdentifier
4212 * args[1] = collectionName
4213 * args[2] = formElement
4214 * @return void
4215 */
4216 getPublisherSubscriber().subscribe('view/inspector/removeCollectionElement/perform', function(topic, args) {
4217 });
4218
4219
4220 .. _apireference-formeditor-basicjavascriptconcepts-events-view-modal-close-perform:
4221
4222 view/modal/close/perform
4223 ++++++++++++++++++++++++
4224
4225 If you try to close the ``form editor`` with unsaved content, a dialog box
4226 appears, asking whether you really wish to close it. If you confirm it, this
4227 event is called in the ``check box`` component. EXT:form uses this event to
4228 close the ``form editor`` and return to the ``form manager``.
4229
4230
4231 Subscribe to the event:
4232
4233 .. code-block:: javascript
4234
4235 /**
4236 * @private
4237 *
4238 * @param string
4239 * @param array
4240 * @return void
4241 */
4242 getPublisherSubscriber().subscribe('view/modal/close/perform', function(topic, args) {
4243 });
4244
4245
4246 .. _apireference-formeditor-basicjavascriptconcepts-events-view-modal-removecollectionelement-perform:
4247
4248 view/modal/removeCollectionElement/perform
4249 ++++++++++++++++++++++++++++++++++++++++++
4250
4251 If you try to remove a validator/ finisher by clicking the remove icon, a
4252 dialog box appears, asking you to confirm this action. If confirmed, this event
4253 is called in the ``check box`` component. EXT:form uses this event to remove
4254 the validator/ finisher from the ``form definition`` through the method
4255 ``getFormEditorApp().getViewModel().removePropertyCollectionElement()``.
4256
4257
4258 Subscribe to the event:
4259
4260 .. code-block:: javascript
4261
4262 /**
4263 * @private
4264 *
4265 * @param string
4266 * @param array
4267 * args[0] = collectionElementIdentifier
4268 * args[1] = collectionName
4269 * args[2] = formElement
4270 * @return void
4271 */
4272 getPublisherSubscriber().subscribe('view/modal/removeCollectionElement/perform', function(topic, args) {
4273 });
4274
4275
4276 .. _apireference-formeditor-basicjavascriptconcepts-events-view-modal-removeformelement-perform:
4277
4278 view/modal/removeFormElement/perform
4279 ++++++++++++++++++++++++++++++++++++
4280
4281 If you try to remove a form element by clicking the remove icon, a dialog box
4282 appears, asking you to confirm this action. If confirmed, this event is called
4283 in the ``check box`` component. EXT:form uses this event to remove the form
4284 element from the ``form definition`` via the method ``getFormEditorApp().getViewModel().removeFormElement()``.
4285
4286
4287 Subscribe to the event:
4288
4289 .. code-block:: javascript
4290
4291 /**
4292 * @private
4293 *
4294 * @param string
4295 * @param array
4296 * args[0] = formElement
4297 * @return void
4298 */
4299 getPublisherSubscriber().subscribe('view/modal/removeFormElement/perform', function(topic, args) {
4300 });
4301
4302
4303 .. _apireference-formeditor-basicjavascriptconcepts-events-view-modal-validationerrors-element-clicked:
4304
4305 view/modal/validationErrors/element/clicked
4306 +++++++++++++++++++++++++++++++++++++++++++
4307
4308 If a form element contains a validation error and you try to save the form, a
4309 dialog box appears, listing all form elements with validation errors. One such
4310 form element can be clicked in this dialog box. This event is called by
4311 clicking a form element in the dialog box. EXT:form uses this event to select
4312 and show this form element.
4313
4314
4315 Subscribe to the event:
4316
4317 .. code-block:: javascript
4318
4319 /**
4320 * @private
4321 *
4322 * @param string
4323 * @param array
4324 * args[0] = formElementIdentifierPath
4325 * @return void
4326 */
4327 getPublisherSubscriber().subscribe('view/modal/validationErrors/element/clicked', function(topic, args) {
4328 });
4329
4330
4331 .. _apireference-formeditor-basicjavascriptconcepts-events-view-paginationnext-clicked:
4332
4333 view/paginationNext/clicked
4334 +++++++++++++++++++++++++++
4335
4336 This event is called if the 'pagination next' button in the ``Stage``
4337 component's header section is clicked. EXT:form uses this event to render the
4338 next page of the form.
4339
4340
4341 Subscribe to the event:
4342
4343 .. code-block:: javascript
4344
4345 /**
4346 * @private
4347 *
4348 * @param string
4349 * @param array
4350 * @return void
4351 */
4352 getPublisherSubscriber().subscribe('view/paginationNext/clicked', function(topic, args) {
4353 });
4354
4355
4356 .. _apireference-formeditor-basicjavascriptconcepts-events-view-paginationprevious-clicked:
4357
4358 view/paginationPrevious/clicked
4359 +++++++++++++++++++++++++++++++
4360
4361 This event is called, if the 'pagination previous' button in the ``Stage``
4362 component's header section is clicked. EXT:form uses this event to render the
4363 previous page of the form.
4364
4365
4366 Subscribe to the event:
4367
4368 .. code-block:: javascript
4369
4370 /**
4371 * @private
4372 *
4373 * @param string
4374 * @param array
4375 * @return void
4376 */
4377 getPublisherSubscriber().subscribe('view/paginationPrevious/clicked', function(topic, args) {
4378 });
4379
4380
4381 .. _apireference-formeditor-basicjavascriptconcepts-events-view-ready:
4382
4383 view/ready
4384 ++++++++++
4385
4386 EXT:form makes it possible to load :ref:`your own JavaScript module <concepts-formeditor-basicjavascriptconcepts-registercustomjavascriptmodules>`.
4387 If all modules are loaded, the view-model method ``_loadAdditionalModules``
4388 calls this event. EXT:form uses this event to remove the preloader icon and
4389 finally initialize the ``form editor``.
4390
4391
4392 Subscribe to the event:
4393
4394 .. code-block:: javascript
4395
4396 /**
4397 * @private
4398 *
4399 * @param string
4400 * @param array
4401 * @return void
4402 */
4403 getPublisherSubscriber().subscribe('view/ready', function(topic, args) {
4404 });
4405
4406
4407 .. _apireference-formeditor-basicjavascriptconcepts-events-view-redobutton-clicked:
4408
4409 view/redoButton/clicked
4410 +++++++++++++++++++++++
4411
4412 This event is called if the redo button in the ``form editor`` header is
4413 clicked. The addition/ deletion and movement of form elements and property
4414 collection elements (validators/ finishers) is saved in an internal stack in
4415 order to reset the undo/ redo functionality. EXT:form uses this event to reset
4416 this stack to the previous state.
4417
4418
4419 Subscribe to the event:
4420
4421 .. code-block:: javascript
4422
4423 /**
4424 * @private
4425 *
4426 * @param string
4427 * @param array
4428 * @return void
4429 */
4430 getPublisherSubscriber().subscribe('view/redoButton/clicked', function(topic, args) {
4431 });
4432
4433
4434 .. _apireference-formeditor-basicjavascriptconcepts-events-view-stage-abstract-button-newelement-clicked:
4435
4436 view/stage/abstract/button/newElement/clicked
4437 +++++++++++++++++++++++++++++++++++++++++++++
4438
4439 This event is called if the "Create new element" button at the end of the
4440 ``Stage`` component in the ``abstract view`` mode is clicked. EXT:form uses
4441 this event to display the "new element" dialog box.
4442
4443
4444 Subscribe to the event:
4445
4446 .. code-block:: javascript
4447
4448 /**
4449 * @private
4450 *
4451 * @param string
4452 * @param array
4453 * args[0] = targetEvent
4454 * args[1] = configuration
4455 * @return void
4456 */
4457 getPublisherSubscriber().subscribe('view/stage/abstract/button/newElement/clicked', function(topic, args) {
4458 });
4459
4460
4461 .. _apireference-formeditor-basicjavascriptconcepts-events-view-stage-abstract-dnd-change:
4462
4463 view/stage/abstract/dnd/change
4464 ++++++++++++++++++++++++++++++
4465
4466 EXT:form uses the jQuery plugin 'jquery.mjs.nestedSortable' for the drag-and-
4467 drop functionality. The 'change' event from 'jquery.mjs.nestedSortable' calls
4468 the ``view/stage/abstract/dnd/change`` event in the ``Stage`` component in the
4469 ``abstract view`` mode if form elements are sorted. EXT:form uses this event to
4470 set various CSS classes during the drag-and-drop process.
4471
4472
4473 Subscribe to the event:
4474
4475 .. code-block:: javascript
4476
4477 /**
4478 * @private
4479 *
4480 * @param string
4481 * @param array
4482 * args[0] = placeholderDomElement
4483 * args[1] = parentFormElementIdentifierPath
4484 * args[2] = enclosingCompositeFormElement
4485 * @return void
4486 */
4487 getPublisherSubscriber().subscribe('view/stage/abstract/dnd/change', function(topic, args) {
4488 });
4489
4490
4491 .. _apireference-formeditor-basicjavascriptconcepts-events-view-stage-abstract-dnd-start:
4492
4493 view/stage/abstract/dnd/start
4494 +++++++++++++++++++++++++++++
4495
4496 EXT:form uses the jQuery plugin 'jquery.mjs.nestedSortable' for the drag-and-
4497 drop functionality. The 'start' event from 'jquery.mjs.nestedSortable' calls
4498 the ``view/stage/abstract/dnd/start`` event in the ``Stage`` component in the
4499 ``abstract view`` mode if form elements are sorted. EXT:form uses this event to
4500 set various CSS classes at the start of the drag-and-drop process.
4501
4502
4503 Subscribe to the event:
4504
4505 .. code-block:: javascript
4506
4507 /**
4508 * @private
4509 *
4510 * @param string
4511 * @param array
4512 * args[0] = draggedFormElementDomElement
4513 * args[1] = draggedFormPlaceholderDomElement
4514 * @return void