TYPO3-Documentation · froemken · Dec 5, 2024 · Nov 25, 2024 · Nov 25, 2024 · Nov 25, 2024
diff --git a/Documentation/CodeSnippets/ExtensionConfiguration/SitePackage-settings.rst.txt b/Documentation/CodeSnippets/ExtensionConfiguration/SitePackage-settings.rst.txt
@@ -7,9 +7,9 @@
 
     styles:
       templates:
-        layoutRootPath: EXT:site_package/Resources/Private/Layouts/ContentElements
-        partialRootPath: EXT:site_package/Resources/Private/Partials/ContentElements
-        templateRootPath: EXT:site_package/Resources/Private/Templates/ContentElements
+        layoutRootPath: EXT:site_package/Resources/Private/ContentElements/Layouts
+        partialRootPath: EXT:site_package/Resources/Private/ContentElements/Partials
+        templateRootPath: EXT:site_package/Resources/Private/ContentElements/Templates
       content:
         textmedia:
           maxW: 1200

diff --git a/Documentation/CodeSnippets/Fluid/Image.rst.txt b/Documentation/CodeSnippets/Fluid/Image.rst.txt
@@ -0,0 +1,10 @@
+..  Generated by https://github.com/TYPO3-Documentation/t3docs-codesnippets
+..  Extracted from EXT:site_package/Resources/Private/ContentElements/Partials/Media/Rendering/Image.html
+
+..  code-block:: html
+    :caption: EXT:site_package/Resources/Private/ContentElements/Partials/Media/Rendering/Image.html
+    :linenos:
+
+    <html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers" data-namespace-typo3-fluid="true">
+    <f:media class="image-embed-item rounded-circle" file="{file}" width="{dimensions.width}" height="{dimensions.height}" alt="{file.alternative}" title="{file.title}" loading="{settings.media.lazyLoading}" decoding="{settings.media.imageDecoding}" />
+    </html>
diff --git a/Documentation/CodeSnippets/Fluid/MenuSitemap.rst.txt b/Documentation/CodeSnippets/Fluid/MenuSitemap.rst.txt
@@ -0,0 +1,31 @@
+..  Generated by https://github.com/TYPO3-Documentation/t3docs-codesnippets
+..  Extracted from EXT:site_package/Resources/Private/ContentElements/Templates/MenuSitemap.html
+
+..  code-block:: html
+    :caption: EXT:site_package/Resources/Private/ContentElements/Templates/MenuSitemap.html
+    :linenos:
+
+    <html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers" data-namespace-typo3-fluid="true">
+    <f:layout name="Default" />
+    <f:section name="Main">
+
+        <f:render section="Menu" arguments="{menu: menu, level: 1}" />
+
+    </f:section>
+    <f:section name="Menu">
+
+        <f:if condition="{menu}">
+            <ul class="list-group ps-4 mt-2">
+                <f:for each="{menu}" as="page">
+                    <li class="list-group-item">
+                        <a href="{page.link}" class="text-decoration-none text-dark {f:if(condition: '{level} < 2', then: 'fw-bold')}">
+                            <span>{page.title}</span>
+                        </a>
+                        <f:render section="Menu" arguments="{menu: page.children, level: '{level + 1}'}" />
+                    </li>
+                </f:for>
+            </ul>
+        </f:if>
+
+    </f:section>
+    </html>
diff --git a/Documentation/CodeSnippets/Fluid/MenuSubpages.rst.txt b/Documentation/CodeSnippets/Fluid/MenuSubpages.rst.txt
@@ -0,0 +1,25 @@
+..  Generated by https://github.com/TYPO3-Documentation/t3docs-codesnippets
+..  Extracted from EXT:site_package/Resources/Private/ContentElements/Templates/MenuSubpages.html
+
+..  code-block:: html
+    :caption: EXT:site_package/Resources/Private/ContentElements/Templates/MenuSubpages.html
+    :linenos:
+
+    <html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers" data-namespace-typo3-fluid="true">
+    <f:layout name="Default" />
+    <f:section name="Main">
+
+        <f:if condition="{menu}">
+            <ul class="nav flex-column">
+                <f:for each="{menu}" as="page">
+                    <li class="nav-item">
+                        <a href="{page.link}" class="nav-link{f:if(condition: 'page.active', then: 'active')}">
+                            <span>{page.title}</span>
+                        </a>
+                    </li>
+                </f:for>
+            </ul>
+        </f:if>
+
+    </f:section>
+    </html>
diff --git a/Documentation/CodeSnippets/codesnippets.php b/Documentation/CodeSnippets/codesnippets.php
@@ -66,4 +66,25 @@
         'caption' => 'EXT:site_package/Resources/Private/Templates/Partials/Navigation/Menu.html',
         'showLineNumbers' => true
     ],
+    [
+        'action' => 'createCodeSnippet',
+        'sourceFile' => 'EXT:site_package/Resources/Private/ContentElements/Templates/MenuSubpages.html',
+        'targetFileName' => 'Fluid/MenuSubpages.rst.txt',
+        'caption' => 'EXT:site_package/Resources/Private/ContentElements/Templates/MenuSubpages.html',
+        'showLineNumbers' => true
+    ],
+    [
+        'action' => 'createCodeSnippet',
+        'sourceFile' => 'EXT:site_package/Resources/Private/ContentElements/Templates/MenuSitemap.html',
+        'targetFileName' => 'Fluid/MenuSitemap.rst.txt',
+        'caption' => 'EXT:site_package/Resources/Private/ContentElements/Templates/MenuSitemap.html',
+        'showLineNumbers' => true
+    ],
+    [
+        'action' => 'createCodeSnippet',
+        'sourceFile' => 'EXT:site_package/Resources/Private/ContentElements/Partials/Media/Rendering/Image.html',
+        'targetFileName' => 'Fluid/Image.rst.txt',
+        'caption' => 'EXT:site_package/Resources/Private/ContentElements/Partials/Media/Rendering/Image.html',
+        'showLineNumbers' => true
+    ],
 ];
diff --git a/Documentation/ContentElementRendering/Index.rst b/Documentation/ContentElementRendering/Index.rst
@@ -0,0 +1,157 @@
+:navigation-title: Content Element rendering
+..  include:: /Includes.rst.txt
+
+..  _content-element-rendering:
+
+====================================================
+Overriding the default templates of content elements
+====================================================
+
+The content elements that are rendered up to this point are rendered by the
+TYPO3 system extension Fluid Styled Content (:composer:`typo3/cms-fluid-styled-content`).
+
+This extensions offers default templates to render content elements. Without
+such an extension, no content would be rendered at all. The default
+templates provided by this extension can be overridden with site settings
+provided by Fluid Styled Content.
+
+..  contents::
+
+..  _content-element-rendering-settings:
+
+Use Settings to override template paths of Fluid Styled Content
+===============================================================
+
+Site settings can be saved both in the site configuration and in the site
+package extension.
+
+We will save the settings to the site package but use the settings editor to
+write the YAML for us.
+
+Go to module :guilabel:`Site Management > Settings` and edit the settings of
+your site. Override the paths to the templates of Fluid Styled Content like this:
+
+..  figure:: /Images/SiteSettingsFsc.png
+    :alt: Screenshot demonstrating the site settings module
+
+    Override the templates of Fluid Styled Content
+
+If you would click :guilabel:`Save` now, the settings would be saved to your
+site configuration at :path:`config/sites/my-site/settings.yaml`. We however
+want to save the settings to the site set of our site package extension.
+
+Click the button :guilabel:`YAML export` to copy the configuration to your
+Clipboard instead, then save it to the following file:
+
+..  code-block:: yaml
+    :caption: packages/site_package/Configuration/Sets/SitePackage/settings.yaml
+
+    styles:
+      templates:
+        templateRootPath: 'EXT:site_package/Resources/Private/ContentElements/Templates'
+        partialRootPath: 'EXT:site_package/Resources/Private/ContentElements/Partials'
+        layoutRootPath: 'EXT:site_package/Resources/Private/ContentElements/Layouts'
+
+Then close the settings editor without saving. You can now start overriding the
+templates:
+
+..  _content-element-rendering-menu-subpages:
+
+Override the "Menu of Subpages" template
+========================================
+
+On "Page 1" of the example data a content element of type "Subpages" was added.
+We now have to find out what this type is called in the database. The raw values
+saved to the database are displayed in the TYPO3 backend when the debug mode
+is activated:
+
+..  figure:: /Images/MenuContentElement.png
+    :alt: Screenshot demonstrating the backend debug mode for Content element "Subpages" on "Page 1"
+
+    You can now see that the Type (saved in field `CType`) is stored as `menu_subpages`
+
+Now we must find and copy the original template from Fluid Styled Content. TYPO3
+extensions are saved by their composer key, here :composer:`typo3/cms-fluid-styled-content`,
+into the folder :path:`vendor` during installation via Composer. You can find
+the files belonging to Fluid Styled Content in folder
+:path:`vendor/typo3/cms-fluid-styled-content` therefore. This folder is
+structured similarly to your site package extension and you can find the original
+templates in folder :path:`Resources/Private/Templates` here.
+
+By convention the templates of Fluid Styled Content have the name of the `CType` in CamelCase. Copy file
+:path:`vendor/typo3/cms-fluid-styled-content/Resources/Private/Templates/MenuSubpages.html`
+into folder :path:`packages/my_site_package/Resources/Private/ContentElements/Templates/MenuSubpages.html`
+
+Edit the file to add some classes as used in menus in Bootstrap, for example
+like this:
+
+..  include:: /CodeSnippets/Fluid/MenuSubpages.rst.txt
+
+In most parts the changes we made are pretty straight forward. In line 9
+we use the `Fluid inline notation <https://docs.typo3.org/permalink/t3coreapi:fluid-inline-notation>`_
+of the :ref:`If ViewHelper <f:if> <t3viewhelper:typo3fluid-fluid-if>` to only
+output class `active` if the page in the menu is in the root line.
+
+..  _content-element-rendering-sitemap:
+
+Override the sitemap template
+=============================
+
+In a similar fashion we now copy and adjust the template for the sitemap from
+:path:`vendor/typo3/cms-fluid-styled-content/Resources/Private/Templates/MenuSitemap.html`
+into folder :path:`packages/site_package/Resources/Private/ContentElements/Templates/MenuSitemap.html`
+and then adjust it:
+
+..  include:: /CodeSnippets/Fluid/MenuSitemap.rst.txt
+
+We want to adjust the HTML output of the sitemap for different levels. The
+original template however gives us no means to output the level.
+
+Line 5 uses the ViewHelper :ref:`Render ViewHelper <f:render> <t3viewhelper:typo3-fluid-render>`
+to render everything in the section defined in lines 8-23.
+
+In the original template the argument `menu` was already passed on as variable to
+the section. We now enhance this line to also pass on variable `level` set to 1.
+
+In line 17 the section `Menu` recursively includes itself to display further
+levels of the sitemap. We now add 1 to the level so that within the recursive
+call we are in level 2.
+
+In line 14 we use that level to determine which class to use for the page link,
+using once more the `Fluid inline notation <https://docs.typo3.org/permalink/t3coreapi:fluid-inline-notation>`_
+of the :ref:`If ViewHelper <f:if> <t3viewhelper:typo3fluid-fluid-if>`.
+
+..  _content-element-rendering-image:
+
+Override the partial template for image rendering
+=================================================
+
+The templates of some content elements use the
+:ref:`Render ViewHelper <f:render> <t3viewhelper:typo3-fluid-render>` to include
+a partial template. This is true wherever images are displayed for example.
+
+Partials in turn can include different partials.
+
+The templates for "Image" and "Textpic" both contain the following line:
+
+..  code-block:: html
+    :caption: vendor/typo3/cms-fluid-styled-content/Resources/Private/Templates/Image.html (Excerpt)
+
+    <f:render partial="Media/Gallery" arguments="{_all}" />
+
+If you open that partial, it includes yet another partial:
+
+..  code-block:: html
+    :caption: vendor/typo3/cms-fluid-styled-content/Resources/Private/Partials/Media/Gallery.html (Excerpt)
+
+    <f:render partial="Media/Type" arguments="{file: column.media, dimensions: column.dimensions, data: data, settings: settings}" />
+
+Which contains another until we finally arrive at
+:path:`vendor/typo3/cms-fluid-styled-content/Resources/Private/Partials/Media/Rendering/Image.html`
+which does contain the actual :ref:`Media ViewHelper <f:media> <t3viewhelper:typo3-fluid-media>`.
+
+By overriding this one partial we can add a class to all images that are
+displayed with the "Image" or "Text with Media" content elements. For example
+we could display all images as circles by adding the class `rounded-circle`:
+
+..  include:: /CodeSnippets/Fluid/Image.rst.txt
diff --git a/Documentation/Images/MenuContentElement.png b/Documentation/Images/MenuContentElement.png
diff --git a/Documentation/Images/SiteSettingsFsc.png b/Documentation/Images/SiteSettingsFsc.png
diff --git a/Documentation/Index.rst b/Documentation/Index.rst
@@ -149,6 +149,7 @@ https://github.com/TYPO3-Documentation/site_package
     TypoScript/Index
     MainMenuCreation/Index
     SiteSets/Index
+    ContentElementRendering/Index
     Faq/Index
     NextSteps/Index