From 07861c0e708cb6a38949b788f26b07f32cf88cd3 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 3 Feb 2025 21:29:47 +0100 Subject: [PATCH] [Backport 13.4] [TASK] List common template locations as files (#5309) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [TASK] List common template locations as files This uses the new rst feature https://github.com/TYPO3-Documentation/render-guides/pull/898 Releases: main, 13.4 * Update Documentation/ExtensionArchitecture/FileStructure/Resources/Private/Index.rst * Update Documentation/ExtensionArchitecture/FileStructure/Resources/Private/Index.rst * Update Documentation/ExtensionArchitecture/FileStructure/Resources/Private/Index.rst * Update Documentation/ExtensionArchitecture/FileStructure/Resources/Private/Index.rst Repair link to PAGEVIEW object * Apply suggestions from code review Co-authored-by: Stefan Frömken * Apply suggestions from code review Co-authored-by: Simon Praetorius * Apply changes from code review * Apply changes from code review * [TASK] Document possibility of different formats in Extbase * Update Documentation/ExtensionArchitecture/FileStructure/Resources/Private/Index.rst --------- Co-authored-by: lina.wolf Co-authored-by: Stefan Frömken Co-authored-by: Lina Wolf <48202465+linawolf@users.noreply.github.com> Co-authored-by: Simon Praetorius --- .../FileStructure/Resources/Private/Index.rst | 164 ++++++++++++++++-- 1 file changed, 151 insertions(+), 13 deletions(-) diff --git a/Documentation/ExtensionArchitecture/FileStructure/Resources/Private/Index.rst b/Documentation/ExtensionArchitecture/FileStructure/Resources/Private/Index.rst index 964a6ff977..c07699224e 100644 --- a/Documentation/ExtensionArchitecture/FileStructure/Resources/Private/Index.rst +++ b/Documentation/ExtensionArchitecture/FileStructure/Resources/Private/Index.rst @@ -3,26 +3,164 @@ Extension development; Resources/Private Folder; Resources/Private Resources; Private -.. _extension-Resources-Private: +.. _extension-resources-private: -================================ -:file:`Private` -================================ +========= +`Private` +========= -.. index:: Path; EXT:{extkey}/Resources/Private/Layouts +This folder contains resources that are needed when rendering a page +but are not needed directly by the browser. This includes: -Resources/Private/Layouts - Main layouts for (Fluid) views. +* Fluid templates +* :ref:`Language files ` +* Files for the compilation of assets like SCSS or TypeScript -.. index:: Path; EXT:{extkey}/Resources/Private/Partials +.. contents:: Table of contents -Resources/Private/Partials - Partial templates for repetitive use. +.. _extension-resources-private-fluid: -.. index:: Path; EXT:{extkey}/Resources/Private/Templates +Fluid templates in the folder Resources/Private +=============================================== -Resources/Private/Templates - One template per action, stored in a folder named after each Controller. +Fluid templates are commonly stored in a folder called +:path:`Resources/Private/Templates`. The concrete location of templates is +configurable via: + +* TypoScript for `PAGEVIEW `_: + :ref:`paths.[priority] ` +* TypoScript for `FLUIDTEMPLATE `_: + :ref:`templateRootPaths ` etc. +* Mails via global configuration: + :ref:`$GLOBALS['TYPO3_CONF_VARS']['MAIL']['templateRootPaths'] ` +* Settings of diverse system or third party extensions like + + * Fluid-Styled Content: :confval:`styles.templates.templateRootPath ` + * Frontend Login: :ref:`felogin.email.templateRootPath ` + +* In some special cases paths might be set in PHP as well, for example when a + ViewFactory is used: `Using the generic view factory (ViewFactoryInterface) `_. + +.. _extension-resources-private-fluid-plugin: + +Common locations for Fluid templates in TYPO3 extensions with plugins: +====================================================================== + +.. typo3:file:: [ActionName].html + :scope: extension + :path: /Resources/Private/Templates/[ControllerName]/ + :regex: /^.*\/Resources\/Private\/Templates(\/[A-Za-z0-9]+)?\/[A-Za-z0-9]+\.[a-z0-9]$/ + :shortDescription: Fluid Template for an extension + + Folder `Templates` often contains the Fluid templates for a TYPO3 extensions + plugins. In Extbase they are stored in a folder with the name of the controller + class (without Controller ending), for example the `NewsController.php` has + the template for action "view" in + :file:`/Resources/Private/Templates/News/View.html`. Non-Extbase controllers + can decide on how to use this folder. + +.. tip:: + Other file endings can be used for different formats, for example `.xml` + for sitemaps or xml-feeds or `.txt` for plain text. + +.. typo3:file:: SomePartials.html + :scope: extension + :path: /Resources/Private/Partials/ + :regex: /^.*\/Resources\/Private\/Partials(\/[A-Za-z0-9]+)*\/[A-Za-z0-9]+\.[a-z0-9]$/ + :shortDescription: Fluid Partials for an extension + + Folder `Partials` often contains the Fluid partials for a TYPO3 extension. + These can be included via the `Render ViewHelper `_ + into the main Fluid template. + +.. typo3:file:: SomeLayout.html + :scope: extension + :path: /Resources/Private/Layouts/ + :regex: /^.*\/Resources\/Private\/Layouts\/[A-Za-z0-9]+\.[a-z0-9]$/ + :shortDescription: Fluid Layouts for an extension + + Folder `Layouts` often contains the Fluid layouts for a TYPO3 extension. + These can be included via the `Layout ViewHelper `_ + into the main Fluid template. + +.. _extension-resources-private-fluid-site-packages: + +Common Fluid template locations for the page view in site packages +================================================================== + +Commonly site package in TYPO3 v13 and above use the `PAGEVIEW `_ +TypoScript object to display the HTML page output. They have one folder, commonly +`PageView` or `Templates` in folder `Resources/Private` with the subfolders +`Pages`, `Partials` and `Layouts` (they cannot be renamed). + +.. typo3:file:: MyPageLayout.html + :scope: extension + :path: /Resources/Private/PageView/Pages/ + :regex: /^.*\/Resources\/Private\/PageView\/Pages\/[A-Za-z0-9]+\.html$/ + :shortDescription: Fluid Templates for different page layouts + + This folder contains one Fluid template for each page layout defined in the + site package. See `Site package Tutorial, the page view `_. + +.. typo3:file:: SomePartials.html + :scope: extension + :path: /Resources/Private/PageView/Partials/ + :regex: /^.*\/Resources\/Private\/PageView\/Partials\/[A-Za-z0-9]+\.html$/ + :shortDescription: Fluid Partials for the page view + + Folder `Partials` contains the Fluid partials used by the page view. + These can be included via the `Render ViewHelper `_ + into the page view template. + +.. typo3:file:: SomeLayout.html + :scope: extension + :path: /Resources/Private/PageView/Layouts/ + :regex: /^.*\/Resources\/Private\/PageView\/Layouts\/[A-Za-z0-9]+\.html$/ + :shortDescription: Fluid Layouts for the page view + + Folder `Layouts` often contains the Fluid layout(s) used by the page view. + These can be included via the `Layout ViewHelper `_ + into the page view template. + +.. _extension-resources-private-fluid-site-fsc: + +Common locations to override Fluid-Styled content elements +========================================================== + +Templates to override or extend Fluid-Styled Content based content objects are +typically stored in a folder called `/Resources/Private/ContentElements`. This +needs to be configured via setting +:confval:`styles.templates.templateRootPath ` +etc. to work. See also `Site Package Tutorial: Overriding the default templates of content elements `_. + +.. typo3:file:: SomeContentElement.html + :scope: extension + :path: /Resources/Private/ContentElements/Pages/ + :regex: /^.*\/Resources\/Private\/ContentElements\/Pages\/[A-Za-z0-9]+\.html$/ + :shortDescription: Fluid Templates for different content elements + + This folder contains one Fluid template for each content element type defined in the + site package. + +.. typo3:file:: SomePartials.html + :scope: extension + :path: /Resources/Private/ContentElements/Partials/ + :regex: /^.*\/Resources\/Private\/ContentElements\/Partials\/[A-Za-z0-9]+\.html$/ + :shortDescription: Fluid Partials for content elements + + Typically overrides the Fluid-Styled Content partials. + +.. typo3:file:: Default.html + :scope: extension + :path: /Resources/Private/ContentElements/Layouts/ + :regex: /^.*\/Resources\/Private\/ContentElements\/Layouts\/Default\.html$/ + :shortDescription: Overrides the default layout for Fluid-styled content elements + + Overrides the default layout originally defined in + `vendor/typo3/cms-fluid-styled-content/Resources/Private/Layouts/Default.html`. + It is possible to define additional custom layouts that can be + included via the `Layout ViewHelper `_ + into content element templates. .. toctree::