..  include:: /Includes.rst.txt

..  _apireference-events:
..  _apireference-formeditor-events:
..  _apireference-formeditor-hooks-beforeformcreate:
..  _apireference-formeditor-hooks-beforeformcreate-connect:
..  _apireference-formeditor-hooks-beforeformcreate-use:
..  _apireference-formeditor-events-beforeformiscreatedevent:
..  _apireference-formeditor-hooks-beforeformduplicate:
..  _apireference-formeditor-hooks-beforeformduplicate-connect:
..  _apireference-formeditor-hooks-beforeformduplicate-use:
..  _apireference-formeditor-hooks-beforeformdelete:
..  _apireference-formeditor-hooks-beforeformdelete-connect:
..  _apireference-formeditor-hooks-beforeformdelete-use:
..  _apireference-frontendrendering-runtimemanipulation-hooks:
..  _apireference-frontendrendering-runtimemanipulation-hooks-initializeformelement:
..  _apireference-frontendrendering-runtimemanipulation-hooks-initializeformelement-connect:
..  _apireference-frontendrendering-runtimemanipulation-hooks-initializeformelement-use:
..  _apireference-frontendrendering-runtimemanipulation-hooks-beforeremovefromparentrenderable:
..  _apireference-frontendrendering-runtimemanipulation-hooks-beforeremovefromparentrenderable-connect:
..  _apireference-frontendrendering-runtimemanipulation-hooks-beforeremovefromparentrenderable-use:
..  _apireference-frontendrendering-runtimemanipulation-hooks-afterbuildingfinished:
..  _apireference-frontendrendering-runtimemanipulation-hooks-afterbuildingfinished-connect:
..  _apireference-frontendrendering-runtimemanipulation-hooks-afterbuildingfinished-use:
..  _apireference-frontendrendering-runtimemanipulation-hooks-afterinitializecurrentpage:
..  _apireference-frontendrendering-runtimemanipulation-hooks-afterinitializecurrentpage-connect:
..  _apireference-frontendrendering-runtimemanipulation-hooks-afterinitializecurrentpage-use:
..  _apireference-frontendrendering-runtimemanipulation-hooks-aftersubmit:
..  _apireference-frontendrendering-runtimemanipulation-hooks-aftersubmit-connect:
..  _apireference-frontendrendering-runtimemanipulation-hooks-aftersubmit-use:
..  _apireference-frontendrendering-runtimemanipulation-hooks-beforerendering:
..  _apireference-frontendrendering-runtimemanipulation-hooks-beforerendering-connect:
..  _apireference-frontendrendering-runtimemanipulation-hooks-beforerendering-use:
..  _apireference-events-legacy-hooks-buildformvalidationconfiguration:
..  _apireference-events-legacy-hooks-afterformstateinitialized:
..  _apireference-events-legacy-hooks:

================
PSR-14 Events
================

EXT:form dispatches PSR-14 events at key points in the lifecycle of a form –
both in the backend form editor and during frontend rendering. These events
are the recommended extension point for developers; the legacy
:php:`$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']` hooks have been removed.

..  seealso::
    The canonical, always-up-to-date reference for all EXT:form events lives
    in the TYPO3 Core API documentation:

    `Form <https://docs.typo3.org/permalink/t3coreapi:eventlist-form>`_

    The extension documentation below provides context, usage notes and
    quick navigation; it intentionally avoids duplicating the full API
    reference.

..  contents::
    :depth: 1
    :local:

..  _apireference-events-backend:

Backend events (form editor / manager)
=======================================

These events are dispatched when an editor creates, saves, duplicates or
deletes a form definition in the TYPO3 backend.

..  _apireference-events-backend-table:

.. list-table::
   :header-rows: 1
   :widths: 40 60

   *  -  Event
      -  When / what can be modified
   *  -  `BeforeFormIsCreatedEvent
         <https://docs.typo3.org/permalink/t3coreapi:beforeformiscreatedevent>`_
      -  Modify the form definition array and/or the persistence identifier
         before a new form is created in the backend.
   *  -  `BeforeFormIsSavedEvent
         <https://docs.typo3.org/permalink/t3coreapi:beforeformissavedevent>`_
      -  Modify the form definition array and/or the persistence identifier
         before a form is saved in the backend.
   *  -  `BeforeFormIsDuplicatedEvent
         <https://docs.typo3.org/permalink/t3coreapi:beforeformisduplicatedevent>`_
      -  Modify the form definition array and/or the persistence identifier
         of the copy before a form is duplicated.
   *  -  `BeforeFormIsDeletedEvent
         <https://docs.typo3.org/permalink/t3coreapi:beforeformisdeletedevent>`_
      -  Dispatched before a form is deleted. Set
         :php:`$event->preventDeletion = true` to abort the deletion (the
         event implements :php:`StoppableEventInterface`).

..  _apireference-events-frontend:

Frontend events (form rendering / runtime)
==========================================

These events are dispatched during form rendering in the frontend.

..  _apireference-events-frontend-table:

.. list-table::
   :header-rows: 1
   :widths: 40 60

   *  -  Event
      -  When / what can be modified
   *  -  `AfterFormIsBuiltEvent
         <https://docs.typo3.org/permalink/t3coreapi:afterformisbuiltevent>`_
      -  Modify the :php:`FormDefinition` object after the form factory has
         finished building the complete form.
   *  -  `BeforeRenderableIsAddedToFormEvent
         <https://docs.typo3.org/permalink/t3coreapi:beforerenderableisaddedtoformevent>`_
      -  Modify or replace a renderable (page, section or element) before it
         is added to the form tree.
   *  -  `BeforeRenderableIsRemovedFromFormEvent
         <https://docs.typo3.org/permalink/t3coreapi:beforerenderableisremovedfromformevent>`_
      -  Dispatched before a renderable is removed from the form tree. Set
         :php:`$event->preventRemoval = true` to abort the removal (the
         event implements :php:`StoppableEventInterface`).
   *  -  `AfterCurrentPageIsResolvedEvent
         <https://docs.typo3.org/permalink/t3coreapi:aftercurrentpageisresolvedevent>`_
      -  Override :php:`$event->currentPage` after the current page has been
         resolved from the request, e.g. to implement conditional page-skip
         logic.
   *  -  `BeforeRenderableIsValidatedEvent
         <https://docs.typo3.org/permalink/t3coreapi:beforerenderableisvalidatedevent>`_
      -  Modify :php:`$event->value` before property-mapping and validation
         run for each submitted form element.
   *  -  `BeforeRenderableIsRenderedEvent
         <https://docs.typo3.org/permalink/t3coreapi:beforerenderableisrenderedevent>`_
      -  Modify the renderable or the :php:`FormRuntime` just before a
         renderable is output to the browser.
   *  -  `BeforeEmailFinisherInitializedEvent
         <https://docs.typo3.org/permalink/t3coreapi:beforeemailfinisherinitializedevent>`_
      -  Modify the options used by the :php:`EmailFinisher` (e.g. recipients,
         subject) before they are applied.
   *  -  `AfterFormStateInitializedEvent
         <https://docs.typo3.org/permalink/t3coreapi:afterformstateinitializedevent>`_
      -  Enrich components with runtime data after the :php:`FormState` has
         been restored from the request (form state and form session are
         both available at this point).
   *  -  `AfterFormDefinitionLoadedEvent
         <https://docs.typo3.org/permalink/t3coreapi:afterformdefinitionloadedevent>`_
      -  Dispatched by :php:`FormPersistenceManager` after a YAML form
         definition has been loaded from disk. Modify the definition globally
         before it reaches the form factory.
   *  -  `AfterFormDefinitionValidationConfigurationIsBuiltEvent
         <https://docs.typo3.org/permalink/t3coreapi:afterformdefinitionvalidationconfigurationisbuiltevent>`_
      -  Dispatched after the form definition validation configuration has
         been built from the form editor setup. Add additional writable
         property paths for custom inspector editor implementations.

..  _apireference-events-register:

Registering an event listener
==============================

Register a listener via the :php:`#[AsEventListener]` PHP attribute:

..  literalinclude:: _codesnippets/_MyFormEventListener.php
    :language: php
    :caption: EXT:my_extension/Classes/EventListener/MyFormEventListener.php


..  seealso::
    :ref:`t3coreapi:EventDispatcher` – TYPO3 Core API documentation on how to
    register and implement PSR-14 event listeners.