[!!!][TASK] Use Record API in Page Module Preview Rendering #1409 (#6162)

Resolves: TYPO3-Documentation/Changelog-To-Doc#1409
Releases: main

Author: linawolf

Documentation/ApiOverview/ContentElements/CustomBackendPreview.rst

@@ -17,6 +17,8 @@ class is responsible for generating the preview and the wrapping.
 The default preview renderer is :php:`\TYPO3\CMS\Backend\Preview\StandardContentPreviewRenderer`
 and handles the Core's built-in content types (field :sql:`CType` in table :sql:`tt_content`).
 
+..  _ContentPreviewRenderer:
+
 Extend the default preview renderer
 ===================================
 
@@ -25,31 +27,43 @@ via page :ref:`TSconfig <ConfigureCE-Preview-PageTSconfig>` or :ref:`event liste
 
 ..  _ConfigureCE-Preview-PageTSconfig:
 
-Page TSconfig
--------------
+Preview rendering with a Fluid template and page TSconfig
+---------------------------------------------------------
+
+..  versionchanged:: 14.0
+    A :php:`\TYPO3\CMS\Core\Domain\RecordInterface` is passed as variable
+    `{record}` to the Fluid Template. The fields are not passed as direct
+    variables anymore. `{pi_flexform_transformed}` has been replaced by
+    `{record.pi_flexform}`. See also `Breaking: #92434 - Use Record API
+    in Page Module Preview Rendering <https://docs.typo3.org/permalink/changelog:breaking-92434-1761644184>`_.
+
 
 This is the "integrator" way, no PHP coding is required. Just some page TSconfig
 and a Fluid template.
 
-..  code-block:: typoscript
+..  literalinclude:: _codesnippets/_preview.typoscript
     :caption: EXT:my_extension/Configuration/page.tsconfig
 
-    mod.web_layout {
-      tt_content {
-        preview {
-          # Your CType
-          example_ctype = EXT:my_extension/Resources/Private/Templates/Preview/ExampleCType.html
-        }
-      }
-    }
+For more details see the :ref:`TSconfig Reference <t3tsref:pageweblayoutpreview>`.
 
 In the Fluid template, the following variables are available:
 
-*     All properties of the :php:`tt_content` row (for example `{uid}`, `{title}`, and `{header}`)
-*     The current record as object (:php:`\TYPO3\CMS\Core\Domain\Record`) in `{record}`
-*     FlexForm settings as array in `{pi_flexform_transformed}`
+*   The current record as object (:php-short:`\TYPO3\CMS\Core\Domain\Record`)
+    in variable `{record}`
 
-For more details see the :ref:`TSconfig Reference <t3tsref:pageweblayoutpreview>`.
+..  literalinclude:: _codesnippets/_Preview.html
+    :caption: EXT:my_extension/Resources/Private/Templates/Preview/MyCType.html
+
+..  rubric:: Migration
+
+..  code-block:: diff
+
+    -<h2>{header}</h2>
+    +<h2>{record.header}</h2>
+    -<p>{bodytext}</p>
+    +<p>{record.bodytext}</p>
+    -<small>{pi_flexform_transformed.settings.welcome_header}</small>
+    +<small>{record.pi_flexform.sheets.s_messages.settings.welcome_header}</small>
 
 ..  _ConfigureCE-Preview-EventListener:
 
@@ -67,9 +81,16 @@ Have a look at this :ref:`showcase implementation <PageContentPreviewRenderingEv
 
 For general information see the chapter on :ref:`implementing an event listener <EventDispatcherImplementation>`.
 
+..  _ConfigureCE-Preview-preview-renderer:
+
 Writing a preview renderer
 ==========================
 
+..  versionchanged:: 14.0
+    The `@internal` class
+    :php-short:`\TYPO3\CMS\Backend\View\BackendLayout\Grid\GridColumnItem` has been
+    updated to work with Record objects.
+
 A custom preview renderer must implement the interface
 :php:`\TYPO3\CMS\Backend\Preview\PreviewRendererInterface` which contains
 the following API methods:

Documentation/ApiOverview/ContentElements/_codesnippets/_Preview.html

@@ -0,0 +1,12 @@
+<h2>{record.header}</h2>
+<p>{record.bodytext}</p>
+<f:if condition="{record.image}">
+    <p>Image UID: {record.image.uid}</p>
+</f:if>
+
+<f:variable name="path" value="s_messages/settings" />
+<small>{record.pi_flexform.{path}.welcome_header}</small>
+
+Or, the following (same result):
+
+<small>{record.pi_flexform.sheets.s_messages.settings.welcome_header}</small>

Documentation/ApiOverview/ContentElements/_codesnippets/_preview.typoscript

@@ -0,0 +1,8 @@
+mod.web_layout {
+  tt_content {
+    preview {
+      # Your CType
+      example_ctype = EXT:my_extension/Resources/Private/Templates/Preview/MyCType.html
+    }
+  }
+}

Documentation/ApiOverview/Events/Events/Backend/PageContentPreviewRenderingEvent.rst

@@ -11,6 +11,14 @@ Use the PSR-14 event
 to ship an alternative rendering for a specific content type or
 to manipulate the record data of a content element.
 
+..  versionchanged:: 14.0
+    `PageContentPreviewRenderingEvent->getRecord()` now returns a
+    :php:`RecordInterface` object instead of an array,
+    :php:`PageContentPreviewRenderingEvent->setRecord()` has been adjusted
+    accordingly.
+
+..  _PageContentPreviewRenderingEvent-example:
+
 Example
 =======
 
@@ -20,6 +28,7 @@ Example
 
 ..  include:: /_includes/EventsAttributeAdded.rst.txt
 
+..  _PageContentPreviewRenderingEvent-api:
 
 API
 ===

Documentation/ApiOverview/Events/Events/Backend/_PageContentPreviewRenderingEvent/_MyEventListener.php

@@ -14,12 +14,15 @@
 {
     public function __invoke(PageContentPreviewRenderingEvent $event): void
     {
-        if ($event->getTable() !== 'tt_content') {
+        if ($event->getRecord()->getFullType() !== 'tt_content.example_ctype') {
             return;
         }
 
-        if ($event->getRecordType() === 'example_ctype') {
-            $event->setPreviewContent('<div>...</div>');
+        if ($event->getRecord()->has('header')) {
+            $header = $event->getRecord()->get('header');
+            $event->setPreviewContent(
+                sprintf('<h1>%s</h1></h1><div>...</div>', $header),
+            );
         }
     }
 }