Skip to content

Commit 6a3d4b5

Browse files
linawolfs2bfroemken
authored
[FEATURE] Show how to override FSC templates (#287)
* [FEATURE] Show how to override FSC templates Releases: main, 13.4 * Apply suggestions from code review Co-authored-by: Simon Praetorius <[email protected]> * [FEATURE] Show how to override FSC templates Releases: main, 13.4 * Apply suggestions from code review Co-authored-by: Stefan Frömken <[email protected]> * Update Documentation/ContentElementRendering/Index.rst --------- Co-authored-by: Simon Praetorius <[email protected]> Co-authored-by: Stefan Frömken <[email protected]>
1 parent 5c86b7f commit 6a3d4b5

File tree

9 files changed

+248
-3
lines changed

9 files changed

+248
-3
lines changed

‎Documentation/CodeSnippets/ExtensionConfiguration/SitePackage-settings.rst.txt‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,9 @@
77
88
styles:
99
templates:
10-
layoutRootPath: EXT:site_package/Resources/Private/Layouts/ContentElements
11-
partialRootPath: EXT:site_package/Resources/Private/Partials/ContentElements
12-
templateRootPath: EXT:site_package/Resources/Private/Templates/ContentElements
10+
layoutRootPath: EXT:site_package/Resources/Private/ContentElements/Layouts
11+
partialRootPath: EXT:site_package/Resources/Private/ContentElements/Partials
12+
templateRootPath: EXT:site_package/Resources/Private/ContentElements/Templates
1313
content:
1414
textmedia:
1515
maxW: 1200

‎Documentation/CodeSnippets/Fluid/Image.rst.txt‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
.. Generated by https://github.com/TYPO3-Documentation/t3docs-codesnippets
2+
.. Extracted from EXT:site_package/Resources/Private/ContentElements/Partials/Media/Rendering/Image.html
3+
4+
.. code-block:: html
5+
:caption: EXT:site_package/Resources/Private/ContentElements/Partials/Media/Rendering/Image.html
6+
:linenos:
7+
8+
<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers" data-namespace-typo3-fluid="true">
9+
<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}" />
10+
</html>

‎Documentation/CodeSnippets/Fluid/MenuSitemap.rst.txt‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
.. Generated by https://github.com/TYPO3-Documentation/t3docs-codesnippets
2+
.. Extracted from EXT:site_package/Resources/Private/ContentElements/Templates/MenuSitemap.html
3+
4+
.. code-block:: html
5+
:caption: EXT:site_package/Resources/Private/ContentElements/Templates/MenuSitemap.html
6+
:linenos:
7+
8+
<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers" data-namespace-typo3-fluid="true">
9+
<f:layout name="Default" />
10+
<f:section name="Main">
11+
12+
<f:render section="Menu" arguments="{menu: menu, level: 1}" />
13+
14+
</f:section>
15+
<f:section name="Menu">
16+
17+
<f:if condition="{menu}">
18+
<ul class="list-group ps-4 mt-2">
19+
<f:for each="{menu}" as="page">
20+
<li class="list-group-item">
21+
<a href="{page.link}" class="text-decoration-none text-dark {f:if(condition: '{level} < 2', then: 'fw-bold')}">
22+
<span>{page.title}</span>
23+
</a>
24+
<f:render section="Menu" arguments="{menu: page.children, level: '{level + 1}'}" />
25+
</li>
26+
</f:for>
27+
</ul>
28+
</f:if>
29+
30+
</f:section>
31+
</html>

‎Documentation/CodeSnippets/Fluid/MenuSubpages.rst.txt‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
.. Generated by https://github.com/TYPO3-Documentation/t3docs-codesnippets
2+
.. Extracted from EXT:site_package/Resources/Private/ContentElements/Templates/MenuSubpages.html
3+
4+
.. code-block:: html
5+
:caption: EXT:site_package/Resources/Private/ContentElements/Templates/MenuSubpages.html
6+
:linenos:
7+
8+
<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers" data-namespace-typo3-fluid="true">
9+
<f:layout name="Default" />
10+
<f:section name="Main">
11+
12+
<f:if condition="{menu}">
13+
<ul class="nav flex-column">
14+
<f:for each="{menu}" as="page">
15+
<li class="nav-item">
16+
<a href="{page.link}" class="nav-link{f:if(condition: 'page.active', then: 'active')}">
17+
<span>{page.title}</span>
18+
</a>
19+
</li>
20+
</f:for>
21+
</ul>
22+
</f:if>
23+
24+
</f:section>
25+
</html>

‎Documentation/CodeSnippets/codesnippets.php‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,4 +66,25 @@
6666
'caption' => 'EXT:site_package/Resources/Private/Templates/Partials/Navigation/Menu.html',
6767
'showLineNumbers' => true
6868
],
69+
[
70+
'action' => 'createCodeSnippet',
71+
'sourceFile' => 'EXT:site_package/Resources/Private/ContentElements/Templates/MenuSubpages.html',
72+
'targetFileName' => 'Fluid/MenuSubpages.rst.txt',
73+
'caption' => 'EXT:site_package/Resources/Private/ContentElements/Templates/MenuSubpages.html',
74+
'showLineNumbers' => true
75+
],
76+
[
77+
'action' => 'createCodeSnippet',
78+
'sourceFile' => 'EXT:site_package/Resources/Private/ContentElements/Templates/MenuSitemap.html',
79+
'targetFileName' => 'Fluid/MenuSitemap.rst.txt',
80+
'caption' => 'EXT:site_package/Resources/Private/ContentElements/Templates/MenuSitemap.html',
81+
'showLineNumbers' => true
82+
],
83+
[
84+
'action' => 'createCodeSnippet',
85+
'sourceFile' => 'EXT:site_package/Resources/Private/ContentElements/Partials/Media/Rendering/Image.html',
86+
'targetFileName' => 'Fluid/Image.rst.txt',
87+
'caption' => 'EXT:site_package/Resources/Private/ContentElements/Partials/Media/Rendering/Image.html',
88+
'showLineNumbers' => true
89+
],
6990
];

‎Documentation/ContentElementRendering/Index.rst‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
:navigation-title: Content Element rendering
2+
.. include:: /Includes.rst.txt
3+
4+
.. _content-element-rendering:
5+
6+
====================================================
7+
Overriding the default templates of content elements
8+
====================================================
9+
10+
The content elements that are rendered up to this point are rendered by the
11+
TYPO3 system extension Fluid Styled Content (:composer:`typo3/cms-fluid-styled-content`).
12+
13+
This extensions offers default templates to render content elements. Without
14+
such an extension, no content would be rendered at all. The default
15+
templates provided by this extension can be overridden with site settings
16+
provided by Fluid Styled Content.
17+
18+
.. contents::
19+
20+
.. _content-element-rendering-settings:
21+
22+
Use Settings to override template paths of Fluid Styled Content
23+
===============================================================
24+
25+
Site settings can be saved both in the site configuration and in the site
26+
package extension.
27+
28+
We will save the settings to the site package but use the settings editor to
29+
write the YAML for us.
30+
31+
Go to module :guilabel:`Site Management > Settings` and edit the settings of
32+
your site. Override the paths to the templates of Fluid Styled Content like this:
33+
34+
.. figure:: /Images/SiteSettingsFsc.png
35+
:alt: Screenshot demonstrating the site settings module
36+
37+
Override the templates of Fluid Styled Content
38+
39+
If you would click :guilabel:`Save` now, the settings would be saved to your
40+
site configuration at :path:`config/sites/my-site/settings.yaml`. We however
41+
want to save the settings to the site set of our site package extension.
42+
43+
Click the button :guilabel:`YAML export` to copy the configuration to your
44+
Clipboard instead, then save it to the following file:
45+
46+
.. code-block:: yaml
47+
:caption: packages/site_package/Configuration/Sets/SitePackage/settings.yaml
48+
49+
styles:
50+
templates:
51+
templateRootPath: 'EXT:site_package/Resources/Private/ContentElements/Templates'
52+
partialRootPath: 'EXT:site_package/Resources/Private/ContentElements/Partials'
53+
layoutRootPath: 'EXT:site_package/Resources/Private/ContentElements/Layouts'
54+
55+
Then close the settings editor without saving. You can now start overriding the
56+
templates:
57+
58+
.. _content-element-rendering-menu-subpages:
59+
60+
Override the "Menu of Subpages" template
61+
========================================
62+
63+
On "Page 1" of the example data a content element of type "Subpages" was added.
64+
We now have to find out what this type is called in the database. The raw values
65+
saved to the database are displayed in the TYPO3 backend when the debug mode
66+
is activated:
67+
68+
.. figure:: /Images/MenuContentElement.png
69+
:alt: Screenshot demonstrating the backend debug mode for Content element "Subpages" on "Page 1"
70+
71+
You can now see that the Type (saved in field `CType`) is stored as `menu_subpages`
72+
73+
Now we must find and copy the original template from Fluid Styled Content. TYPO3
74+
extensions are saved by their composer key, here :composer:`typo3/cms-fluid-styled-content`,
75+
into the folder :path:`vendor` during installation via Composer. You can find
76+
the files belonging to Fluid Styled Content in folder
77+
:path:`vendor/typo3/cms-fluid-styled-content` therefore. This folder is
78+
structured similarly to your site package extension and you can find the original
79+
templates in folder :path:`Resources/Private/Templates` here.
80+
81+
By convention the templates of Fluid Styled Content have the name of the `CType` in CamelCase. Copy file
82+
:path:`vendor/typo3/cms-fluid-styled-content/Resources/Private/Templates/MenuSubpages.html`
83+
into folder :path:`packages/my_site_package/Resources/Private/ContentElements/Templates/MenuSubpages.html`
84+
85+
Edit the file to add some classes as used in menus in Bootstrap, for example
86+
like this:
87+
88+
.. include:: /CodeSnippets/Fluid/MenuSubpages.rst.txt
89+
90+
In most parts the changes we made are pretty straight forward. In line 9
91+
we use the `Fluid inline notation <https://docs.typo3.org/permalink/t3coreapi:fluid-inline-notation>`_
92+
of the :ref:`If ViewHelper <f:if> <t3viewhelper:typo3fluid-fluid-if>` to only
93+
output class `active` if the page in the menu is in the root line.
94+
95+
.. _content-element-rendering-sitemap:
96+
97+
Override the sitemap template
98+
=============================
99+
100+
In a similar fashion we now copy and adjust the template for the sitemap from
101+
:path:`vendor/typo3/cms-fluid-styled-content/Resources/Private/Templates/MenuSitemap.html`
102+
into folder :path:`packages/site_package/Resources/Private/ContentElements/Templates/MenuSitemap.html`
103+
and then adjust it:
104+
105+
.. include:: /CodeSnippets/Fluid/MenuSitemap.rst.txt
106+
107+
We want to adjust the HTML output of the sitemap for different levels. The
108+
original template however gives us no means to output the level.
109+
110+
Line 5 uses the ViewHelper :ref:`Render ViewHelper <f:render> <t3viewhelper:typo3-fluid-render>`
111+
to render everything in the section defined in lines 8-23.
112+
113+
In the original template the argument `menu` was already passed on as variable to
114+
the section. We now enhance this line to also pass on variable `level` set to 1.
115+
116+
In line 17 the section `Menu` recursively includes itself to display further
117+
levels of the sitemap. We now add 1 to the level so that within the recursive
118+
call we are in level 2.
119+
120+
In line 14 we use that level to determine which class to use for the page link,
121+
using once more the `Fluid inline notation <https://docs.typo3.org/permalink/t3coreapi:fluid-inline-notation>`_
122+
of the :ref:`If ViewHelper <f:if> <t3viewhelper:typo3fluid-fluid-if>`.
123+
124+
.. _content-element-rendering-image:
125+
126+
Override the partial template for image rendering
127+
=================================================
128+
129+
The templates of some content elements use the
130+
:ref:`Render ViewHelper <f:render> <t3viewhelper:typo3-fluid-render>` to include
131+
a partial template. This is true wherever images are displayed for example.
132+
133+
Partials in turn can include different partials.
134+
135+
The templates for "Image" and "Textpic" both contain the following line:
136+
137+
.. code-block:: html
138+
:caption: vendor/typo3/cms-fluid-styled-content/Resources/Private/Templates/Image.html (Excerpt)
139+
140+
<f:render partial="Media/Gallery" arguments="{_all}" />
141+
142+
If you open that partial, it includes yet another partial:
143+
144+
.. code-block:: html
145+
:caption: vendor/typo3/cms-fluid-styled-content/Resources/Private/Partials/Media/Gallery.html (Excerpt)
146+
147+
<f:render partial="Media/Type" arguments="{file: column.media, dimensions: column.dimensions, data: data, settings: settings}" />
148+
149+
Which contains another until we finally arrive at
150+
:path:`vendor/typo3/cms-fluid-styled-content/Resources/Private/Partials/Media/Rendering/Image.html`
151+
which does contain the actual :ref:`Media ViewHelper <f:media> <t3viewhelper:typo3-fluid-media>`.
152+
153+
By overriding this one partial we can add a class to all images that are
154+
displayed with the "Image" or "Text with Media" content elements. For example
155+
we could display all images as circles by adding the class `rounded-circle`:
156+
157+
.. include:: /CodeSnippets/Fluid/Image.rst.txt

‎Documentation/Images/MenuContentElement.png‎

14.2 KB
Loading

‎Documentation/Images/SiteSettingsFsc.png‎

56.1 KB
Loading

‎Documentation/Index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,7 @@ https://github.com/TYPO3-Documentation/site_package
149149
TypoScript/Index
150150
MainMenuCreation/Index
151151
SiteSets/Index
152+
ContentElementRendering/Index
152153
Faq/Index
153154
NextSteps/Index
154155

0 commit comments

Comments
 (0)