From b8ce3e12bd0471be868c60aa4ccade96f37aca18 Mon Sep 17 00:00:00 2001
From: Mikkel Ricky <rimi@aarhus.dk>
Date: Sun, 15 Dec 2024 18:10:30 +0100
Subject: [PATCH] Added documentation on JavaScript events

---
 doc/events.rst                 | 43 ++++++++++++++++++++++++++++++++++
 doc/fields/CollectionField.rst | 25 ++++++++++++++++++++
 2 files changed, 68 insertions(+)

diff --git a/doc/events.rst b/doc/events.rst
index 2ac91fad8b..c1245acc19 100644
--- a/doc/events.rst
+++ b/doc/events.rst
@@ -77,4 +77,47 @@ property of the ``BlogPost`` entity before persisting it:
         }
     }
 
+JavaScript Events
+-----------------
+
+EasyAdmin triggers some `JavaScript events`_ when the user interacts with entity forms:
+
+================================  ==============================================  ================================  ==========
+Event type                        Occurs when                                     Event detail                      Cancelable
+================================  ==============================================  ================================  ==========
+``'ea.form.error'``               User submits a form that has validation errors  ``{page: pageName, form: form}``  true
+--------------------------------  ----------------------------------------------  --------------------------  ----------
+``'ea.form.submit'``              User submits a form                             ``{page: pageName, form: form}``  true
+--------------------------------  ----------------------------------------------  --------------------------------  ----------
+``'ea.collection.item-added'``    Item added to collection                        ``{newElement: element}``         false
+--------------------------------  ----------------------------------------------  --------------------------------  ----------
+``'ea.collection.item-removed'``  Item removed from collection                                                      false
+================================  ==============================================  ================================  ==========
+
+(see `CustomEvent: detail property
+<https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/detail>`_ for
+details on "Event detail" and `Event: cancelable property
+<https://developer.mozilla.org/en-US/docs/Web/API/Event/cancelable>`_ for
+details on "Cancelable".)
+
+Example usage:
+
+  .. code-block:: javascript
+
+     document.addEventListener('ea.form.error', (event) => {
+       const {page, form} = event.detail
+       alert(`The ${page} form contains errors. Please resolve these before submitting again.`)
+     })
+
+     document.addEventListener('ea.form.submit', (event) => {
+       const {page, form} = event.detail
+       console.debug(`${page} form submitted`, form)
+     })
+
+See :doc:`Collection Field JavaScript Events
+</fields/CollectionField#javascript-events>` for details on and example use of
+the ``'ea.collection.*'`` events.
+
+
 .. _`Symfony events`: https://symfony.com/doc/current/event_dispatcher.html
+.. _`JavaScript events`: https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Events
diff --git a/doc/fields/CollectionField.rst b/doc/fields/CollectionField.rst
index 9d41ba0c41..2bba8d9eb1 100644
--- a/doc/fields/CollectionField.rst
+++ b/doc/fields/CollectionField.rst
@@ -195,5 +195,30 @@ class name of the controller as the first argument::
 
     The ``useEntryCrudForm()`` method requires Symfony 6.1 or newer version.
 
+JavaScript Events
+-----------------
+
+When an item is added to a collection field, a `CustomEvent
+<https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent>`_ with type
+``'ea.collection.item-added'`` is dispatched, and when an item is removed, an
+`Event <https://developer.mozilla.org/en-US/docs/Web/API/Event/Event>`_ with
+type ``'ea.collection.item-removed'`` dispatched.
+
+The ``'ea.collection.item-added'`` event contains information about the added
+item in the `detail property
+<https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/detail>`_:
+
+  .. code-block:: javascript
+
+     document.addEventListener('ea.collection.item-added', (event) => {
+       const {newElement} = event.detail
+       console.debug(newElement, 'added to collection')
+     })
+
+     document.addEventListener('ea.collection.item-removed', (event) => {
+       // Do something with the event
+       console.debug('item removed from collection')
+     })
+
 .. _`CollectionType`: https://symfony.com/doc/current/reference/forms/types/collection.html
 .. _`documentation about Symfony CollectionType options`: https://symfony.com/doc/current/reference/forms/types/collection.html#field-options