minor #6650 Added documentation on JavaScript events (rimi-itk)

This PR was merged into the 4.x branch.

Discussion
----------

Added documentation on JavaScript events

First stab at adding the missing JavaScripts events documentation (cf. #5922).

I've added a general overview of all JavaScript events on the Events page and details on collection events on the Collection Field page. Any suggestions on other or better ways to organize the event documentation are welcome.

I've tried to document the additional information, if any, available in the event, i.e. the event's `detail` property value, but I'm not sure if I've done it in the best way possible. Any suggestions for improvements are welcome.

Commits
-------

b8ce3e1 Added documentation on JavaScript events

Author: javiereguiluz

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

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