Skip to content

Commit c95cfee

Browse files
linawolflinawolf
committed
[TASK] [FEATURE] Introduce Fluid render.contentArea/record ViewHelpers
References: TYPO3-Documentation/Changelog-To-Doc#1563 Releases: main
1 parent 9fa148a commit c95cfee

3 files changed

Lines changed: 323 additions & 41 deletions

File tree

‎Documentation/Global/CObject.rst‎

Lines changed: 54 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,14 @@
77
CObject ViewHelper `<f:cObject>`
88
================================
99

10+
.. versionchanged:: 14.2
11+
Instead of using the :html:`<f:cObject>` ViewHelper to render database records,
12+
the new `Render.record ViewHelper <f:render.record> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-render-record>`_
13+
ViewHelper can be used to render database records and the new
14+
`Render.contentArea ViewHelper <f:render.contentArea> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-render-contentarea>`_
15+
can be used to render all content elements within a column from a backend
16+
layout.
17+
1018
.. typo3:viewhelper:: cObject
1119
:display: tags,description,gitHubLink
1220
:source: ../Global.json
@@ -45,36 +53,6 @@ The TypoScript could look like this:
4553
lib.someLibObject = TEXT
4654
lib.someLibObject.value = Hello World!
4755

48-
.. _typo3-fluid-cobject-content:
49-
50-
Displaying content elements provided by the page-content data processor
51-
-----------------------------------------------------------------------
52-
53-
When using the `page-content data processor <https://docs.typo3.org/permalink/t3tsref:pagecontentfetchingprocessor>`_
54-
to display the content elements of a
55-
`PAGEVIEW <https://docs.typo3.org/permalink/t3tsref:cobj-pageview>`_,
56-
the CObject ViewHelper can be used to display the actual content elements:
57-
58-
.. code-block:: html
59-
:caption: packages/my_sitepackage/Resources/Private/Templates/Pages/Default.html
60-
61-
<f:for each="{myContent.left.records}" as="contentElement">
62-
<f:cObject
63-
typoscriptObjectPath="{contentElement.mainType}"
64-
table="{contentElement.mainType}"
65-
data="{contentElement}"
66-
/>
67-
</f:for>
68-
69-
Variable `{contentElement.mainType}` already contains the correct TypoScript path
70-
to the TypoScript top-level object `tt_content <https://docs.typo3.org/permalink/t3tsref:tlo-tt-content>`_.
71-
72-
The table storing the content elements is also called `tt_content` so we can use
73-
the same variable here. Variable `contentElement` already contains the
74-
`Record object <https://docs.typo3.org/permalink/t3coreapi:record-objects>`_
75-
containing the data needed to render the content element with the
76-
CObject ViewHelper.
77-
7856
.. _typo3-fluid-cobject-plugin:
7957

8058
Use data from a plugin in TypoScript
@@ -127,7 +105,7 @@ content data from a Fluid template to a content object defined in TypoScript. Th
127105
following example demonstrates this with a user counter. The user counter is in
128106
a blog post (the blog post has a count of how many times it has been viewed.)
129107

130-
Add the viewhelper to your Fluid template. This can be done in 3 different
108+
Add the Viewhelper to your Fluid template. This can be done in 3 different
131109
ways. The basic tag syntax:
132110

133111
.. code-block:: html
@@ -251,3 +229,48 @@ easier to understand.
251229

252230
In summary, the cObject ViewHelper is a powerful option to embed TypoScript
253231
expressions in Fluid templates.
232+
233+
.. _typo3-fluid-cobject-migration:
234+
235+
Migration from the `f:cObject` to dedicated ViewHelpers for special cases
236+
=========================================================================
237+
238+
.. _typo3-fluid-cobject-content:
239+
240+
Migration: Use the `f:render.contentArea` ViewHelper
241+
----------------------------------------------------
242+
243+
.. versionchanged:: 14.2
244+
Instead of using the :html:`<f:cObject>` ViewHelper to the new
245+
`Render.contentArea ViewHelper <f:render.contentArea> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-render-contentarea>`_
246+
can be used to render all content elements within a column from a backend
247+
layout.
248+
249+
When using the `page-content data processor <https://docs.typo3.org/permalink/t3tsref:pagecontentfetchingprocessor>`_
250+
to display the content elements of a
251+
`PAGEVIEW <https://docs.typo3.org/permalink/t3tsref:cobj-pageview>`_, switch
252+
to using the
253+
`Render.contentArea ViewHelper <f:render.contentArea> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-render-contentarea>`_
254+
on dropping TYPO3 v13 support:
255+
256+
.. code-block:: diff
257+
:caption: packages/my_sitepackage/Resources/Private/Templates/Pages/Default.html (diff)
258+
259+
- <f:for each="{myContent.left.records}" as="contentElement">
260+
- <f:cObject
261+
- typoscriptObjectPath="{contentElement.mainType}"
262+
- table="{contentElement.mainType}"
263+
- data="{contentElement}"
264+
- />
265+
- </f:for>
266+
267+
+ <f:render.contentArea contentArea="{myContent.left}" />
268+
269+
Variable `{contentElement.mainType}` already contains the correct TypoScript path
270+
to the TypoScript top-level object `tt_content <https://docs.typo3.org/permalink/t3tsref:tlo-tt-content>`_.
271+
272+
The table storing the content elements is also called `tt_content` so we can use
273+
the same variable here. Variable `contentElement` already contains the
274+
`Record object <https://docs.typo3.org/permalink/t3coreapi:record-objects>`_
275+
containing the data needed to render the content element with the
276+
CObject ViewHelper.

‎Documentation/Global/Render/ContentArea.rst‎

Lines changed: 100 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,3 @@
1-
.. This reStructured text file has been automatically generated, do not change.
2-
.. Source: https://github.com/TYPO3/typo3/blob/main/typo3/sysext/fluid/Classes/ViewHelpers/Render/ContentAreaViewHelper.php
3-
4-
:edit-on-github-link: https://github.com/TYPO3/typo3/edit/main/typo3/sysext/fluid/Classes/ViewHelpers/Render/ContentAreaViewHelper.php
51
:navigation-title: render.contentArea
62

73
.. include:: /Includes.rst.txt
@@ -12,5 +8,104 @@
128
Render.contentArea ViewHelper `<f:render.contentArea>`
139
======================================================
1410

11+
.. versionadded:: 14.2
12+
Instead of using the :html:`<f:cObject>` and :html:`<f:for>` ViewHelpers to
13+
render content areas, use the new :html:`<f:render.contentArea>` ViewHelper.
14+
15+
This ViewHelper can be used to render a content area provided by the
16+
`page-content data processor <https://docs.typo3.org/permalink/t3tsref:pagecontentfetchingprocessor>`_.
17+
18+
It is commonly used with the `PAGEVIEW <https://docs.typo3.org/permalink/t3tsref:cobj-pageview>`_
19+
TypoScript content object.
20+
21+
Theme creators are encouraged to use the :html:`<f:render.contentArea>` ViewHelper
22+
to allow other extensions to modify the output via event listeners.
23+
24+
.. typo3:viewhelper:: render.contentArea
25+
:source: /Global.json
26+
:display: tags,gitHubLink
27+
:noindex:
28+
29+
.. contents:: Table of contents
30+
31+
.. _typo3-fluid-render-contentarea-example:
32+
33+
Rendering all content elements within a column from a backend layout
34+
====================================================================
35+
36+
The most common use case for the `<f:render.contentArea>` is to render all
37+
content elements within a column from a backend layout.
38+
39+
.. tabs::
40+
41+
.. group-tab:: Fluid
42+
43+
.. code-block:: html
44+
:caption: packages/my_sitepackage/Resources/Private/Templates/Page/Default.html
45+
46+
<f:render.contentArea contentArea="{content.main}"/>
47+
48+
Or using inline syntax:
49+
50+
.. code-block:: html
51+
:caption: packages/my_sitepackage/Resources/Private/Templates/Page/Default.html
52+
53+
{content.main -> f:render.contentArea()}
54+
55+
.. group-tab:: TypoScript
56+
57+
.. code-block:: typoscript
58+
:caption: packages/my_sitepackage/Configuration/Sets/main/setup.typoscript
59+
60+
page = PAGE
61+
page {
62+
10 = PAGEVIEW
63+
10 {
64+
paths.10 = EXT:my_sitepackage/Resources/Private/Templates/
65+
dataProcessing.10 = page-content
66+
}
67+
}
68+
69+
For an example of how to configure the backend layout in page TSconfig
70+
and for further options in the data processor, see
71+
`Example: Use the page-content data processor to display the content
72+
<https://docs.typo3.org/permalink/t3tsref:pagecontentfetchingprocessor-example>`_.
73+
74+
.. _typo3-fluid-render-contentarea-example-recordas:
75+
76+
Using the "recordAs" argument to wrap each content element
77+
==========================================================
78+
79+
Using the :ref:`recordAs <t3viewhelper:viewhelper-argument-typo3-cms-fluid-viewhelpers-render-contentareaviewhelper-recordas>`
80+
argument, the `<f:render.contentArea>` can be used in combination with the
81+
`Render.record ViewHelper <f:render.record> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-render-record>`_
82+
to wrap each content element:
83+
84+
.. code-block:: html
85+
:caption: packages/my_sitepackage/Resources/Private/Templates/Page/Default.html
86+
87+
<div id="sidebar">
88+
<f:render.contentArea contentArea="{content.left}" recordAs="record">
89+
<div id="sidebarItem{record.uid}">
90+
<f:render.record record="{record}" />
91+
</div>
92+
</f:render.contentArea>
93+
</div>
94+
95+
.. _typo3-fluid-render-contentarea-event:
96+
97+
Intercepting the rendering of content areas via an event
98+
========================================================
99+
100+
With the :php:`\TYPO3\CMS\Fluid\Event\ModifyRenderedContentAreaEvent`,
101+
developers can intercept the rendering of content areas in Fluid templates to
102+
modify the output.
103+
104+
.. _typo3-fluid-render-contentarea-arguments:
105+
106+
Arguments of the `<f:render.contentArea>` ViewHelper
107+
====================================================
108+
15109
.. typo3:viewhelper:: render.contentArea
16-
:source: ../../Global.json
110+
:source: /Global.json
111+
:display: arguments-only

0 commit comments

Comments
 (0)