typo3/sysext/form/Documentation/ApiReference/Index.rst

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