diff --git a/Documentation/CodeSnippets/ExtensionConfiguration/SitePackage-settings.rst.txt b/Documentation/CodeSnippets/ExtensionConfiguration/SitePackage-settings.rst.txt index cc09d093..f73b7ead 100644 --- 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 new file mode 100644 index 00000000..32b3ecdf --- /dev/null +++ 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: + + + + diff --git a/Documentation/CodeSnippets/Fluid/MenuSitemap.rst.txt b/Documentation/CodeSnippets/Fluid/MenuSitemap.rst.txt new file mode 100644 index 00000000..ffcc1de6 --- /dev/null +++ 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: + + + + + + + + + + + + + + + + diff --git a/Documentation/CodeSnippets/Fluid/MenuSubpages.rst.txt b/Documentation/CodeSnippets/Fluid/MenuSubpages.rst.txt new file mode 100644 index 00000000..aaf080b2 --- /dev/null +++ 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: + + + + + + + + + + + diff --git a/Documentation/CodeSnippets/codesnippets.php b/Documentation/CodeSnippets/codesnippets.php index 6ba45d36..57cac3fc 100644 --- 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 new file mode 100644 index 00000000..bdfbb35d --- /dev/null +++ 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 `_ +of the :ref:`If ViewHelper ` 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 ` +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 `_ +of the :ref:`If ViewHelper `. + +.. _content-element-rendering-image: + +Override the partial template for image rendering +================================================= + +The templates of some content elements use the +:ref:`Render ViewHelper ` 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) + + + +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) + + + +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 `. + +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 new file mode 100644 index 00000000..cd91afad Binary files /dev/null and b/Documentation/Images/MenuContentElement.png differ diff --git a/Documentation/Images/SiteSettingsFsc.png b/Documentation/Images/SiteSettingsFsc.png new file mode 100644 index 00000000..903ad1e9 Binary files /dev/null and b/Documentation/Images/SiteSettingsFsc.png differ diff --git a/Documentation/Index.rst b/Documentation/Index.rst index 50d51028..a009dd17 100644 --- 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