TYPO3 v15 dev-main snapshot ()

2026-08-10 22:31:09 +02:00
commit af8cc155b5
6818 changed files with 642608 additions and 0 deletions
@@ -0,0 +1,158 @@
+..  include:: /Includes.rst.txt
+
+..  _feature-108868-1770281522:
+
+===========================================================
+Feature: #108868 - Introduce Fluid f:render.text ViewHelper
+===========================================================
+
+See :issue:`108868`
+
+Description
+===========
+
+A new :html:`<f:render.text>` ViewHelper has been added. It provides a consistent
+approach for outputting field values in templates where the field is part of a
+record.
+
+The ViewHelper follows the same conventions as other rendering-related
+ViewHelpers and can be used wherever a text-based database field needs to be
+displayed in the frontend.
+
+The ViewHelper is record-aware. It receives the full record and field name,
+and renders the field according to the field's TCA configuration. This includes
+both plain text and rich text fields.
+
+By default, accessing a field that is not available in a record
+raises an exception. In order to support shared templates that need to be rendered even
+if a field is missing, the optional boolean argument :html:`optional` can be set
+to :html:`true`. The ViewHelper will then return :html:`null` instead.
+
+The input can be a :php-short:`\TYPO3\CMS\Core\Domain\RecordInterface`,
+:php-short:`\TYPO3\CMS\Frontend\Page\PageInformation`, or a
+:php-short:`\TYPO3\CMS\Extbase\DomainObject\DomainObjectInterface`.
+
+This means records, ContentBlockData objects, PageInformation
+objects, and Extbase models can be input. PageInformation objects and Extbase models are
+converted internally to a RecordInterface.
+
+Usage
+=====
+
+Usage with the :typoscript:`record-transformation` data processor:
+
+..  code-block:: typoscript
+
+    dataProcessing {
+        10 = record-transformation
+    }
+
+Based on the field's TCA configuration of the record in question, the ViewHelper
+chooses the appropriate processing of the field (plain text, multiline text, or
+rich text) without needing further configuration in the template.
+
+..  code-block:: html
+    :caption: MyContentElement.fluid.html
+
+    <f:render.text record="{record}" field="title" />
+    or
+    <f:render.text field="title">{record}</f:render.text>
+    or
+    {f:render.text(record: record, field: 'title')}
+    or
+    {record -> f:render.text(field: 'title')}
+
+Usage with optional fields:
+
+..  code-block:: html
+    :caption: SharedHeader.fluid.html
+
+    <f:variable name="header">{record -> f:render.text(field: 'header', optional: true)}</f:variable>
+
+This is useful for shared partials, for example in
+:html:`fluid_styled_content`. A header partial can be reused by content
+elements whose transformed record does not provide a :html:`header` or
+:html:`subheader` field. Without :html:`optional="true"`, rendering such a
+partial would raise a :php:`RecordPropertyNotFoundException`. With
+:html:`optional="true"`, the ViewHelper returns :html:`null` and the partial can
+continue to handle the missing value gracefully.
+
+Usage with an Extbase model (property name differs from database field name):
+
+The :html:`field` argument always refers to the database or TCA column name of
+the underlying record, even if your Extbase model maps that column to a
+differently named property.
+
+Note that Extbase models need to contain all columns to be rendered and
+the record type column (if configured in TCA) for this to work correctly. For
+example, an Extbase model that represents `tt_content` must map both `bodytext`
+and `CType` to be able to use
+:html:`<f:render.text record="{contentModel}" field="bodytext" />`.
+
+..  code-block:: html
+    :caption: Blog/Templates/Post/Show.fluid.html
+
+    <f:render.text record="{post}" field="short_description" />
+
+    <!-- Example: Post->shortDescription maps to DB field "short_description";
+         use field="short_description" here. -->
+
+Previously, you needed to choose different processing for plain text and rich
+text fields. You can now use the same ViewHelper for all field types.
+
+**For reference, similar results could previously be achieved using:**
+
+..  code-block:: html
+    :caption: MyContentElement.fluid.html
+
+    {record.title}
+
+or multiline text:
+
+..  code-block:: html
+    :caption: MyContentElement.fluid.html
+
+    <f:format.nl2br>{record.description}</f:format.nl2br>
+    or
+    {record.description -> f:format.nl2br()}
+
+or, for rich text:
+
+..  code-block:: html
+    :caption: MyContentElement.fluid.html
+
+    <f:format.html>{record.bodytext}</f:format.html>
+    or
+    {record.bodytext -> f:format.html()}
+
+Migration
+=========
+
+Extensions that previously accessed field values with
+:html:`{record.title}` can continue to do so. However, using
+:html:`<f:render.text>` is recommended instead because it renders the field in the
+context of the record and applies processing based on the field configuration.
+
+When migrating from formatting ViewHelpers like :html:`<f:format.nl2br>` or
+:html:`<f:format.html>` to :html:`<f:render.text>`, the main difference is that
+the new ViewHelper is aware of the record it belongs to and renders the field
+based on the record's TCA schema.
+
+If a template intentionally accesses fields that might not be available in every
+record, for example shared :html:`fluid_styled_content` header partials
+used by custom content elements that do not have a visible :html:`header` field, use the
+:html:`optional` argument to preserve the previous behavior of treating the
+missing field as empty output.
+
+Impact
+======
+
+Theme creators are encouraged to use the :html:`<f:render.text>` ViewHelper for
+rendering text-based fields (plain text and rich text) as it provides a
+standardized, record-aware approach that can be built upon in future versions.
+
+The ViewHelper takes both the record and the field name as arguments so the
+rendering process has access to the complete record context. This makes the
+ViewHelper more flexible than directly accessing the field value.
+
+..  index:: Frontend, ext:fluid