diff --git a/Documentation/Global/CObject.rst b/Documentation/Global/CObject.rst index 61b1034..5c8137c 100644 --- a/Documentation/Global/CObject.rst +++ b/Documentation/Global/CObject.rst @@ -7,6 +7,14 @@ CObject ViewHelper `` ================================ +.. versionchanged:: 14.2 + Instead of using the :html:`` ViewHelper to render database records, + the new `Render.record ViewHelper `_ + ViewHelper can be used to render database records and the new + `Render.contentArea ViewHelper `_ + can be used to render all content elements within a column from a backend + layout. + .. typo3:viewhelper:: cObject :display: tags,description,gitHubLink :source: ../Global.json @@ -45,36 +53,6 @@ The TypoScript could look like this: lib.someLibObject = TEXT lib.someLibObject.value = Hello World! -.. _typo3-fluid-cobject-content: - -Displaying content elements provided by the page-content data processor ------------------------------------------------------------------------ - -When using the `page-content data processor `_ -to display the content elements of a -`PAGEVIEW `_, -the CObject ViewHelper can be used to display the actual content elements: - -.. code-block:: html - :caption: packages/my_sitepackage/Resources/Private/Templates/Pages/Default.html - - - - - -Variable `{contentElement.mainType}` already contains the correct TypoScript path -to the TypoScript top-level object `tt_content `_. - -The table storing the content elements is also called `tt_content` so we can use -the same variable here. Variable `contentElement` already contains the -`Record object `_ -containing the data needed to render the content element with the -CObject ViewHelper. - .. _typo3-fluid-cobject-plugin: 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 following example demonstrates this with a user counter. The user counter is in a blog post (the blog post has a count of how many times it has been viewed.) -Add the viewhelper to your Fluid template. This can be done in 3 different +Add the Viewhelper to your Fluid template. This can be done in 3 different ways. The basic tag syntax: .. code-block:: html @@ -251,3 +229,48 @@ easier to understand. In summary, the cObject ViewHelper is a powerful option to embed TypoScript expressions in Fluid templates. + +.. _typo3-fluid-cobject-migration: + +Migration from the `f:cObject` to dedicated ViewHelpers for special cases +========================================================================= + +.. _typo3-fluid-cobject-content: + +Migration: Use the `f:render.contentArea` ViewHelper +---------------------------------------------------- + +.. versionchanged:: 14.2 + Instead of using the :html:`` ViewHelper, the new + `Render.contentArea ViewHelper `_ + can be used to render all content elements within a column from a backend + layout. + +If you are using the `page-content data processor `_ +to display the content elements of a +`PAGEVIEW `_, switch +to the +`Render.contentArea ViewHelper `_ +on dropping TYPO3 v13 support: + +.. code-block:: diff + :caption: packages/my_sitepackage/Resources/Private/Templates/Pages/Default.html (diff) + + - + - + - + + + + +Variable `{contentElement.mainType}` already contains the correct TypoScript path +to the TypoScript top-level object `tt_content `_. + +The table storing the content elements is also called `tt_content`, so we can use +the same variable here. Variable `contentElement` will already contain the +`Record object `_ +containing the data needed to render the content element with the +CObject ViewHelper. diff --git a/Documentation/Global/Render/ContentArea.rst b/Documentation/Global/Render/ContentArea.rst index 1e1862f..1e0aebf 100644 --- a/Documentation/Global/Render/ContentArea.rst +++ b/Documentation/Global/Render/ContentArea.rst @@ -1,7 +1,3 @@ -.. This reStructured text file has been automatically generated, do not change. -.. Source: https://github.com/TYPO3/typo3/blob/main/typo3/sysext/fluid/Classes/ViewHelpers/Render/ContentAreaViewHelper.php - -:edit-on-github-link: https://github.com/TYPO3/typo3/edit/main/typo3/sysext/fluid/Classes/ViewHelpers/Render/ContentAreaViewHelper.php :navigation-title: render.contentArea .. include:: /Includes.rst.txt @@ -12,5 +8,103 @@ Render.contentArea ViewHelper `` ====================================================== +.. versionadded:: 14.2 + Instead of using the :html:`` and :html:`` ViewHelpers to + render content areas, use the new :html:`` ViewHelper. + +This ViewHelper can be used to render a content area provided by the +`page-content data processor `_. + +It is commonly used with the `PAGEVIEW `_ +TypoScript content object. + +Theme creators are encouraged to use the :html:`` ViewHelper +to allow other extensions to modify the output via event listeners. + +.. typo3:viewhelper:: render.contentArea + :source: /Global.json + :display: tags,gitHubLink + :noindex: + +.. contents:: Table of contents + +.. _typo3-fluid-render-contentarea-example: + +Rendering all content elements within a backend layout column +============================================================= + +The most common use case for the `` is to render all +content elements within a column from a backend layout. + +.. tabs:: + + .. group-tab:: Fluid + + .. code-block:: html + :caption: packages/my_sitepackage/Resources/Private/Templates/Page/Default.html + + + + Or using inline syntax: + + .. code-block:: html + :caption: packages/my_sitepackage/Resources/Private/Templates/Page/Default.html + + {content.main -> f:render.contentArea()} + + .. group-tab:: TypoScript + + .. code-block:: typoscript + :caption: packages/my_sitepackage/Configuration/Sets/main/setup.typoscript + + page = PAGE + page { + 10 = PAGEVIEW + 10 { + paths.10 = EXT:my_sitepackage/Resources/Private/Templates/ + dataProcessing.10 = page-content + } + } + +For an example of how to configure the backend layout in page TSconfig +and further data processor options, see +`Example: Use the page-content data processor to display the content +`_. + +.. _typo3-fluid-render-contentarea-example-recordas: + +Using the "recordAs" argument to wrap each content element +========================================================== + +Using the :ref:`recordAs ` +argument, `` can be combined with the +`Render.record ViewHelper `_ +to wrap each content element: + +.. code-block:: html + :caption: packages/my_sitepackage/Resources/Private/Templates/Page/Default.html + + + +.. _typo3-fluid-render-contentarea-event: + +Intercepting the rendering of content areas via an event +======================================================== + +Developers can intercept the rendering of content areas in Fluid templates using +:php:`\TYPO3\CMS\Fluid\Event\ModifyRenderedContentAreaEvent` to modify output. + +.. _typo3-fluid-render-contentarea-arguments: + +Arguments of the `` ViewHelper +==================================================== + .. typo3:viewhelper:: render.contentArea - :source: ../../Global.json + :source: /Global.json + :display: arguments-only diff --git a/Documentation/Global/Render/Record.rst b/Documentation/Global/Render/Record.rst index 9b02e02..8b5cfff 100644 --- a/Documentation/Global/Render/Record.rst +++ b/Documentation/Global/Render/Record.rst @@ -1,7 +1,3 @@ -.. This reStructured text file has been automatically generated, do not change. -.. Source: https://github.com/TYPO3/typo3/blob/main/typo3/sysext/fluid/Classes/ViewHelpers/Render/RecordViewHelper.php - -:edit-on-github-link: https://github.com/TYPO3/typo3/edit/main/typo3/sysext/fluid/Classes/ViewHelpers/Render/RecordViewHelper.php :navigation-title: render.record .. include:: /Includes.rst.txt @@ -12,5 +8,173 @@ Render.record ViewHelper `` ============================================ +.. versionadded:: 14.2 + Instead of using the :html:`` ViewHelper to render database records, + use the new :html:`` ViewHelper. + +This ViewHelper renders a record object via its TypoScript definition. The +most common use case is rendering a content element that is available as a +record object in a Fluid template. + +By default, the ViewHelper renders the record as-is. However, event listeners +can listen to the :php:`\TYPO3\CMS\Fluid\Event\ModifyRenderedRecordEvent` +to modify the output. + +.. typo3:viewhelper:: render.record + :source: /Global.json + :display: tags,gitHubLink + :noindex: + +.. contents:: Table of contents + +.. _typo3-fluid-render-record-example: + +Rendering content elements using the `record-transformation` data processor +=========================================================================== + +.. tabs:: + + .. group-tab:: Fluid + + .. code-block:: html + :caption: packages/my_sitepackage/Resources/Private/Templates/Content/MyContent.html + + + + Or using inline syntax: + + .. code-block:: html + :caption: packages/my_sitepackage/Resources/Private/Templates/Content/Default.html + + {record -> f:render.record()} + + .. group-tab:: TypoScript + + .. code-block:: typoscript + :caption: packages/my_sitepackage/Configuration/Sets/main/setup.typoscript + + dataProcessing { + 10 = record-transformation + } + +.. _typo3-fluid-render-record-example-any: + +Rendering arbitrary database records +==================================== + +You can render any database record that has valid +`TCA `_, including categories and +records provided by third-party extensions. + +.. _typo3-fluid-render-record-example-category: + +Rendering system categories +--------------------------- + +You can render not only `tt_content` records but any database record by defining +a top-level TypoScript object with the name of the record table. + +For example, to render system categories, use `sys_category = FLUIDTEMPLATE` +(`FLUIDTEMPLATE `_) +to configure the rendering. + +.. tabs:: + + .. group-tab:: TypoScript rendering definition + + .. code-block:: typoscript + :caption: packages/my_sitepackage/Configuration/Sets/main/setup.typoscript + + sys_category = FLUIDTEMPLATE + sys_category { + file = EXT:my_sitepackage/Resources/Private/Templates/Category/Default.html + layoutRootPaths.10 = EXT:my_sitepackage/Resources/Private/Layouts/Category/ + partialRootPaths.10 = EXT:my_extension/Resources/Private/Partials/Category/ + dataProcessing.1774685451 = record-transformation + } + + .. group-tab:: Fluid + + .. code-block:: html + :caption: EXT:my_sitepackage/Resources/Private/Templates/Partials/Categories.html + + + {category -> f:render.record()} + + + .. group-tab:: TypoScript page definition + + .. code-block:: typoscript + :caption: packages/my_sitepackage/Configuration/Sets/main/setup.typoscript + + page = PAGE + page { + 10 = PAGEVIEW + 10 { + paths.10 = EXT:my_sitepackage/Resources/Private/Templates/ + dataProcessing { + 10 = database-query + 10 { + as = categories + table = sys_category + where = parent=0 + dataProcessing.1774685450 = record-transformation + } + } + } + } + + +.. _typo3-fluid-render-record-example-type: + +Rendering records with types +============================ + +If you want to render a database record that has different +`types `_, you can +use a TypoScript `Content object array (COA) `_ +to configure rendering for special types: + +.. code-block:: typoscript + :caption: packages/my_sitepackage/Configuration/Sets/main/setup.typoscript + + tx_myextension_domain_model_product = COA + tx_myextension_domain_model_product { + key { + field = my_type + } + default = FLUIDTEMPLATE + default { + templateName > + templateName.ifEmpty.cObject = TEXT + templateName.ifEmpty.cObject { + field = record_type + required = 1 + case = uppercamelcase + } + # for record_type = 'mainProduct' the template file my_extension/Resources/Private/Templates/Product/MainProduct.html will be used + templateRootPaths.10 = EXT:my_extension/Resources/Private/Templates/Product/ + layoutRootPaths.10 = EXT:my_extension/Resources/Private/Layouts/ + partialRootPaths.10 = EXT:my_extension/Resources/Private/Partials/ + dataProcessing.1421884800 = record-transformation + } + mySpecialType.templateRootPaths.20 = EXT:my_extension/Resources/Private/Templates/ProductSpecial/ + } + +.. _typo3-fluid-render-record-event: + +Intercepting the rendering of records via events +================================================ + +With the :php:`\TYPO3\CMS\Fluid\Event\ModifyRenderedRecordEvent`, developers can +intercept the rendering of individual records in Fluid templates to modify the +output. + +.. _typo3-fluid-render-record-arguments: + +Arguments of the `` ViewHelper +=============================================== + .. typo3:viewhelper:: render.record - :source: ../../Global.json + :source: /Global.json + :display: arguments-only