159 lines
5.7 KiB
ReStructuredText
159 lines
5.7 KiB
ReStructuredText
.. 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
|