Study guide · Page Rendering and Site Sets
How a page is built: site sets, PAGEVIEW and content areas
In TYPO3 14, a page is built along a clear path. A site set brings the configuration, PAGEVIEW picks the Fluid template, the backend layout defines the content areas, and a ViewHelper outputs them. On this page you build that path once from start to finish. Afterwards you know which file goes where and which value applies in the end.
The example: Lindenau Music School
The integrator Mara builds the website of the Lindenau Music School. The project is a Composer project with TYPO3 14.3. Everything that makes up the website lives in its own site package: an extension with the key lindenau_site and the Composer name lindenau/site.
The website has a home page, pages for subjects such as piano and violin, a concert calendar and a sidebar with contact details.
What a site set is
A site set is a reusable package of site configuration. It can contain settings, TypoScript, page TSconfig and route enhancers. A page tree, users or content are not part of it.
Sets always come from extensions. A folder in fileadmin is not enough. For the sets of a project, you therefore create a site package, which is your own extension for the website. That is exactly what lindenau_site is.
Each set gets its own subfolder in Configuration/Sets of the extension. Mara creates the folder Site there. Only one file inside it is required: config.yaml. It contains:
- the name, a globally unique identifier in the form vendor, slash, set name, here lindenau and site,
- the label, which is the readable name in the selection in the backend,
- the dependencies, which are sets this set cannot work without,
- optionally optionalDependencies and the flag hidden.
name: lindenau/site
label: 'Lindenau Music School'
dependencies:
- typo3/fluid-styled-content
- lindenau/base
optionalDependencies:
- typo3/formThe folder name is not the identifier. TYPO3 finds the set by its name. Settings such as rootPageId or base with the domain do not belong in a set. They live in the site configuration, because they apply to exactly one website.
Required or optional: If a set from dependencies is missing, TYPO3 reports an error. A set from optionalDependencies is loaded when it is available and skipped without an error otherwise. You only make a dependency optional if your own set also works without it. Neither variant installs a missing extension.
Hidden building blocks: Mara has a second set, lindenau/base, that only defines settings. It should not show up in the selection in the backend. So she sets the flag hidden to true in its config.yaml. The set then no longer appears in the selection or in the default output of the command site:sets:list. It still works as a dependency.
Activating: Installing the extension only makes a set available. It takes effect once a site adds it as a dependency. You do this in the site's config.yaml under dependencies, or in the backend in the module Sites, Setup.
base: 'https://www.musikschule-lindenau.de/'
rootPageId: 1
dependencies:
- lindenau/siteTYPO3 resolves dependencies recursively. Every dependency comes before the set that needs it. If two sets need the same set, TYPO3 loads it only once. This gives a fixed dependency order, which is the same for settings, TypoScript, page TSconfig and route enhancers.
The files in the set folder
Next to config.yaml, TYPO3 finds these files by itself when they are in the set folder:
settings.definitions.yamldefines your own settings with type and default value.settings.yamloverrides values of settings that are already defined.labels.xlftranslates the labels of the set and its settings.setup.typoscriptandconstants.typoscriptprovide TypoScript.page.tsconfigprovides page TSconfig for all pages of the sites that use the set.route-enhancers.yamlprovides route enhancers. This file is new in TYPO3 14, since version 14.1 to be precise.
PHP files such as ext_localconf.php or the composer.json are not among them. No registration in PHP is needed.
TypoScript through dependencies: If Mara's set needs the TypoScript of Fluid Styled Content, she adds its set under dependencies. She does not import the files herself, and she does not add a static template in a record. Only this way can TYPO3 work out the order and remove duplicates. An @import within your own set is fine, though.
Sets and old template records: If you use site sets, you should no longer use TypoScript records. During a transition there is sometimes both. Then you must switch off the two Clear flags for constants and setup in the record. If either one is on, TYPO3 throws away the TypoScript from the sets, and it never reaches the frontend. Moving to sets completely is the better choice.
Route enhancers: In route-enhancers.yaml, the enhancers sit below the key routeEnhancers, just like in the site configuration. The file is found automatically and supports YAML imports. It does not need an @import from another file. TYPO3 merges the enhancers of the sets in dependency order. A later set overrides an earlier one. In the end, the site configuration takes precedence over all enhancers from sets.
Settings: define, override, translate
Settings replace the old TypoScript constants and can do more. Every setting has a type, a default value and a label. From these, TYPO3 builds a suitable input field in the module Sites, Settings.
Defining: You define a setting of your own in settings.definitions.yaml. It holds the identifier, type, default value, label and description. In her helper set, Mara defines a color for the page header.
settings:
lindenau.headerColor:
label: 'Header color'
type: color
default: '#ffffff'The type decides the validation and the input field. TYPO3 14.3 knows these types:
- int for whole numbers, and number for whole or decimal numbers,
- bool for yes or no,
- string for one line of text, and text for text with several lines,
- stringlist for a list of texts,
- color for a color,
- page for a page from the page tree,
- url for a web address.
There is no type image or json.
Overriding: In settings.yaml, a set only sets new values. This works for settings that the set itself or one of its dependencies defines. The definition stays where it comes from and is not copied. If Mara wants to change the maximum image width of Fluid Styled Content, she does not change its definitions file. She depends on its set and writes only the new value into her own settings.yaml.
styles.content.textmedia.maxW: 1200
lindenau.headerColor: '#386492'Which value applies? Settings are built in layers. At the bottom is the default value from the definition. On top of it come the values of the sets in dependency order. At the very top is the site itself, with its own settings.yaml in the site folder. Whatever editors save in the module Sites, Settings ends up exactly there.
This does not cause an error about duplicate values. Each higher layer simply overrides the one below.
Translating: You can leave the labels out of the YAML file and put them into a labels.xlf next to config.yaml. The IDs follow a fixed pattern:
- The set itself has the ID label.
- The label of a setting has the ID settings, dot, identifier. For lindenau.headerColor that is
settings.lindenau.headerColor. - The description has the ID settings, dot, description, dot, identifier.
- Categories have the ID categories, dot, category name.
Translations into other languages sit next to it with a language prefix, for example de.labels.xlf.
Reading: In TypoScript, settings are available like constants. In the Fluid template, you reach them through the site object, that is through site.settings.
PAGEVIEW: the page template by convention
PAGEVIEW is a TypoScript content object. It outputs the HTML body of a page with Fluid templates. Unlike the older FLUIDTEMPLATE, it follows fixed rules for folders and file names. That is why it needs much less configuration. Mara writes only this into the setup.typoscript of her set:
page = PAGE
page.10 = PAGEVIEW
page.10.paths.100 = EXT:lindenau_site/Resources/Private/PageView/Fixed subfolders: Below every given path, PAGEVIEW looks for the page templates in the folder Pages. Layouts go in the folder Layouts, and partials in the folder Partials. A folder called Templates plays no role here.
Which template? PAGEVIEW derives the file name from the backend layout of the page. By convention, the layout twoColumns uses the file TwoColumns.html in the folder Pages, with an uppercase first letter. However, Fluid 5 first tries the spelling from the layout and only then the variant with an uppercase first letter. Stick to the convention, and there are never two candidates.
Variables in the template: Without further configuration, these variables are available:
- site is the site object. Through it you reach the site settings with
site.settingsand the title of the website. - language is the current language of the site.
- page holds the data of the current page.
- settings holds the TypoScript constants of the page.
- content holds the content areas of the backend layout, since TYPO3 14.2.
Variables such as backendUser or the POST data of the request are not available there. You add more variables with the property variables. The names site, language and page are reserved.
<h1>{page.pageRecord.title}</h1>
<header style="background: {site.settings.lindenau.headerColor}">Overriding templates: The property paths is a list with priorities. TYPO3 searches it from the highest to the lowest number. A second set, for example for a summer look, adds a path with a higher number, such as 200. If a template is in that path, it is preferred. Missing files still come from the path with number 100. If you set the same number again instead, you only replace the old path.
FLUIDTEMPLATE in comparison
FLUIDTEMPLATE still exists in TYPO3 14, for example for content elements. You set the name and paths of the template yourself. For this it has properties that PAGEVIEW does not know: templateName, templateRootPaths, layoutRootPaths and partialRootPaths.
lib.concert = FLUIDTEMPLATE
lib.concert {
templateName = Concert
templateRootPaths.10 = EXT:lindenau_site/Resources/Private/Templates/
variables.hall = TEXT
variables.hall.value = Great Hall
settings.showDate = 1
}With both objects, you pass a variable of your own under variables. A content object such as TEXT goes there, and its result appears in the template under the chosen name. Values under settings end up in the variable settings. Data processors add more data.
The differences at a glance:
- PAGEVIEW derives the template from the backend layout and expects fixed subfolders such as Pages and Layouts. With FLUIDTEMPLATE you set the template and paths yourself.
- Both know dataProcessing and variables.
- FLUIDTEMPLATE was not removed in TYPO3 14. For whole pages, however, PAGEVIEW is the recommended way.
Data processors prepare data
In the database, data is often stored in a form a template cannot do much with. The field tt_content.assets, for example, only stores information about file relations. Data processors turn such raw data into objects and arrays that the template can use directly. They do not save, compress or translate anything.
The property dataProcessing exists on FLUIDTEMPLATE and on PAGEVIEW. A TEXT object or a menu built with HMENU has no data processors.
The TYPO3 Core ships these data processors, each with a short alias:
- The MenuProcessor with the alias menu builds navigations, such as the main navigation or a breadcrumb.
- The FilesProcessor with the alias files turns file relations into usable FileReference objects, which Fluid can use to output images, for example.
- The FlexFormProcessor with the alias flex-form converts the XML of a FlexForm field into an array.
- The PageContentFetchingProcessor with the alias page-content provides the content of all columns of the backend layout.
- There are also the CommaSeparatedValueProcessor, the DatabaseQueryProcessor, the GalleryProcessor, the LanguageMenuProcessor, the SiteProcessor, the SiteLanguageProcessor, the SplitProcessor and the RecordTransformationProcessor.
The Core has no processor for PDF export or image optimization. Developers can, however, write data processors of their own.
Nesting: A data processor can have its own dataProcessing property. Mara wants to show an image for each subject in the main menu. The MenuProcessor builds the menu, and a FilesProcessor inside it loads the images from the page field media for each menu item. In the same way, you can nest a FilesProcessor in a FlexFormProcessor to resolve file relations from the FlexForm.
page.10.dataProcessing.10 = menu
page.10.dataProcessing.10 {
as = mainMenu
dataProcessing.10 = files
dataProcessing.10.references.fieldName = media
}Backend layouts: the content areas of a page
A backend layout defines the content areas of a page. It describes a grid of rows and columns. Each column is an area that editors fill with content in the module Content, Layout.
Where to define them? Best practice is page TSconfig, so for Mara the page.tsconfig of her set. The layout then lives as a file in the site package and therefore under version control. Backend layouts as records in the page tree still work. They are no longer considered best practice, though, because they are not in the repository and must be maintained by hand in every environment.
A column knows these settings:
- name is the label in the backend.
- colPos is the number of the column. It is stored in the field colPos of every content element. That is how TYPO3 knows which column an element is in.
- identifier is a readable name such as main. It becomes the variable name in the template.
- colspan and rowspan control width and height in the grid. They are optional.
- slideMode controls inheritance from parent pages and is optional too.
So for a column to be usable in the template, it needs colPos and identifier. The other fields of a content element have other jobs. pid is the page, sorting the order and CType the type of the element.
mod.web_layout.BackendLayouts.twoColumns {
title = Two columns
config.backend_layout {
colCount = 2
rowCount = 1
rows.1.columns {
1 {
name = Main content
colPos = 0
identifier = main
}
2 {
name = Sidebar
colPos = 1
identifier = sidebar
slideMode = collectReverse
allowedContentTypes = text, image
}
}
}
}Content from parent pages: With slideMode, a column inherits content from the rootline. There are three values:
- slide takes the content of the nearest parent page that has something in this column. This only applies when the column is empty on the current page.
- collect merges the content of the page and all parent pages. It starts with the topmost page, and the content of the current page comes last.
- collectReverse does the same in reverse order. It starts with the current page and ends with the topmost one.
With an empty value, the column inherits nothing. A slider or collapsing a column in the backend has nothing to do with slideMode.
Allowed content types: Since TYPO3 14, version 14.1 to be precise, each column can define which content types are allowed in it. There is allowedContentTypes for an allow list and disallowedContentTypes for a deny list. Both are comma-separated lists of CType values. The wizard for new content elements then shows only matching types. Previously you needed an extension such as content_defender for this.
Rendering content with f:render.contentArea
Now the content is still missing from the template. The way there leads through content areas.
The data processor page-content loads the content of all columns of the backend layout. Without the option as, the variable is called content. Inside it, each column gets a content area, an object of the type ContentArea, under the identifier of the column. So the column main is available as content.main. The area knows the settings of the column, such as colPos and slideMode. Its records are Record objects with fields such as header or fullType. The processor does not deliver finished HTML or just a list of uid values.
Since TYPO3 14.2, PAGEVIEW even creates this variable content by itself. You choose a different name there with the property contentAs. You then mainly need the processor for FLUIDTEMPLATE.
The ViewHelper f:render.contentArea is new in TYPO3 14, since version 14.2 to be precise. It outputs all content elements of an area. It replaces the former combination of a loop with f:for and the ViewHelper f:cObject. It is meant for page templates with PAGEVIEW. It does not load the content from the database itself. It expects a ContentArea object. If it gets anything else, such as a list of uid values as text, it throws an exception.
There are two notations: as a tag with the argument contentArea, and inline with an arrow after the variable.
<f:render.contentArea contentArea="{content.main}" />
{content.main -> f:render.contentArea()}Your own markup around each element: Mara wants to wrap every element of the sidebar in a card. For this she sets the argument recordAs. Then each element is available as a variable of its own. Inside the ViewHelper, f:render.record outputs the element. Any markup can come before and after it.
<f:render.contentArea contentArea="{content.sidebar}" recordAs="record">
<div class="card">
<f:render.record record="{record}" />
</div>
</f:render.contentArea>The Fluid view and cache busting
Template, layout and partial work together in Fluid. The template holds the content of a page or an action. The layout is the frame around it. Partials are reusable building blocks such as the contact card. The template picks a layout with the ViewHelper f:layout. The layout inserts the sections of the template with f:render and the argument section. You include partials with f:render and the argument partial, as often as you like.
The view from the inside: Behind PAGEVIEW and FLUIDTEMPLATE there is a Fluid view. You pass variables with assign(), or several at once with assignMultiple(). After that, render() produces the output. The paths for templates, layouts and partials are lists with fallback: Fluid takes the first matching file, from the highest number downwards. In TYPO3 14, PHP code creates a view through the ViewFactoryInterface. The old StandaloneView no longer exists.
$view->assign('concert', $concert);
$view->assignMultiple(['teachers' => $teachers, 'rooms' => $rooms]);
$html = $view->render();The file extension fluid.html: Fluid 5 in TYPO3 14 introduces the optional extension fluid.html, for example TwoColumns.fluid.html. It is looked for before the extension html. Old file names keep working. The extension is a convention and does not change escaping.
Including files: For CSS, JavaScript or images from the folder Resources/Public of an extension, you use the ViewHelper f:uri.resource. It returns the public URL of the file. Pages, by contrast, are linked with f:link.page and Extbase actions with f:uri.action.
<link rel="stylesheet" href="{f:uri.resource(path: 'EXT:lindenau_site/Resources/Public/Css/main.css')}">Cache busting makes sure that visitors load the new version of a file after a change. Browsers keep CSS and JavaScript files for a long time. So TYPO3 adds the timestamp of the last change to the URL. When the file changes, the URL changes, and the browser loads it again. It does not make the file smaller or encrypt it.
With f:uri.resource, the argument useCacheBusting is on by default. So you do not have to switch it on. If you set it to false, you get the URL without a timestamp. The ViewHelper never adds a random number.
Where does the timestamp go? That is controlled by the setting versionNumberInFilename in the FE section of the system configuration:
- By default it is false. Then the timestamp is added as a query string after a question mark, for example main.css, question mark, 1767225600.
- If it is true, the timestamp goes into the file name, for example main.1767225600.css.
A file with that name does not actually exist. So the web server must send the request to the real file with a rewrite rule. The .htaccess shipped with TYPO3 contains such a rule. If it is missing, for example on nginx without a matching rule, all CSS files included this way answer with 404.
Key points
- A site set is a reusable package with settings, TypoScript, page TSconfig and route enhancers. It lives in an extension under
Configuration/Sets. - Only config.yaml is required. It holds the name, label and dependencies. A set takes effect only as a dependency of a site.
- You define settings in settings.definitions.yaml and override them in settings.yaml. The site itself wins.
- With site sets, switch off the Clear flags in old template records, or better use no records at all.
- PAGEVIEW looks for templates in the folder Pages and names them after the backend layout with an uppercase first letter. Without a layout the rootline applies, otherwise Default.
- In the PAGEVIEW template, site, language, page, settings and content are available. You read site settings through
site.settings. - FLUIDTEMPLATE still exists. There you set templateName and the paths yourself.
- Data processors prepare data, can be nested and belong to FLUIDTEMPLATE and PAGEVIEW.
- Backend layouts belong in page TSconfig. Every column needs colPos and identifier.
- The ViewHelper f:render.contentArea outputs a content area and replaces f:for with f:cObject.
- f:uri.resource adds a timestamp by default. If it goes into the file name, the web server needs rewrite rules.
Terms
- Site set
- Reusable package of site configuration from an extension.
- Site package
- Your own extension that brings everything for one particular website.
- Site setting
- Setting with a type and a default value that a site can override.
- PAGEVIEW
- Content object that outputs the page with Fluid by fixed rules.
- FLUIDTEMPLATE
- Content object that renders a freely chosen Fluid template.
- Data processor
- Building block that prepares raw data for a Fluid template.
- Backend layout
- Grid of rows and columns that defines the content areas of a page.
- colPos
- Number of the column in which a content element is stored.
- ContentArea
- Content area of a column with its settings and its records.
- Cache busting
- Timestamp in the URL so that browsers load changed files again.