feat: add example for BeforeRecordLanguageOverlayEvent (#5251)

* feat: add example for BeforeRecordLanguageOverlayEvent

Additionally, link BeforeRecordLanguageOverlayEvent and AfterRecordLanguageOverlayEvent.

Releases: main, 13.4

* Update BeforeRecordLanguageOverlayEvent.rst

---------

Co-authored-by: Lina Wolf <[email protected]>

Author: brotkrueml

Documentation/ApiOverview/Events/Events/Core/Domain/AfterRecordLanguageOverlayEvent.rst

@@ -14,6 +14,9 @@ The PSR-14 event :php:`\TYPO3\CMS\Core\Domain\Event\AfterRecordLanguageOverlayEv
 can be used to modify the actual translated record (if found) to add additional
 information or perform custom processing of the record.
 
+..  seealso::
+    *   :ref:`BeforeRecordLanguageOverlayEvent`
+
 Example
 =======
 

Documentation/ApiOverview/Events/Events/Core/Domain/BeforeRecordLanguageOverlayEvent.rst

@@ -15,10 +15,25 @@ can be used to modify information (such as the
 :ref:`LanguageAspect <context_api_aspects_language>` or the actual incoming
 record from the database) before the database is queried.
 
-Example
-=======
+..  seealso::
+    *   :ref:`AfterRecordLanguageOverlayEvent`
 
-..  include:: /_includes/EventsContributeNote.rst.txt
+..  _BeforeRecordLanguageOverlayEvent-example:
+
+Example: Change the overlay type to "on" (connected)
+====================================================
+
+In this example, we will change the overlay type to "on" (connected). This may
+be necessary if your site is configured with free mode, but you have a record
+type that has languages connected.
+
+..  literalinclude:: _BeforeRecordLanguageOverlayEvent/_MyEventListener.php
+    :language: php
+    :caption: EXT:my_extension/Classes/Domain/Language/MyEventListener.php
+
+..  include:: /_includes/EventsAttributeAdded.rst.txt
+
+..  _BeforeRecordLanguageOverlayEvent-api:
 
 API
 ===

Documentation/ApiOverview/Events/Events/Core/Domain/_BeforeRecordLanguageOverlayEvent/_MyEventListener.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MyVendor\MyExtension\Domain\Language;
+
+use TYPO3\CMS\Core\Attribute\AsEventListener;
+use TYPO3\CMS\Core\Context\LanguageAspect;
+use TYPO3\CMS\Core\Domain\Event\BeforeRecordLanguageOverlayEvent;
+
+#[AsEventListener(
+    identifier: 'my-extension/before-record-language-overlay',
+)]
+final readonly class MyEventListener
+{
+    public function __invoke(BeforeRecordLanguageOverlayEvent $event): void
+    {
+        if ($event->getTable() !== 'tx_myextension_domain_model_record') {
+            return;
+        }
+
+        $currentLanguageAspect = $event->getLanguageAspect();
+        $newLanguageAspect = new LanguageAspect(
+            $currentLanguageAspect->getId(),
+            $currentLanguageAspect->getContentId(),
+            LanguageAspect::OVERLAYS_ON,
+            $currentLanguageAspect->getFallbackChain(),
+        );
+
+        $event->setLanguageAspect($newLanguageAspect);
+    }
+}