Skip to content

[Backport 13.4] [DOCS] Overhaul fluid templates #367

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
linawolf merged 3 commits into from
Oct 31, 2025
Merged

[Backport 13.4] [DOCS] Overhaul fluid templates #367

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0f3881b
[DOCS] Overhaul fluid templates
sarahmccarthy123 Oct 30, 2025
71f2001
Fix capitalization of 'Fluid' in Index.rst
linawolf Oct 31, 2025
cfd37c4
Apply suggestion from @linawolf
linawolf Oct 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions Documentation/FluidTemplates/FromTheScratch.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@

.. _fluid-templates-scratch:

================================
Fluid Templates from the Scratch
================================
============================
Fluid Templates from Scratch
============================


.. contents::
Expand Down
124 changes: 61 additions & 63 deletions Documentation/FluidTemplates/Index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,25 +7,25 @@
Fluid Templates
===============

To understand the following section you need basic knowledge about how to use the
To understand the following section you need basic knowledge of the
:ref:`Fluid templating engine <t3start:fluid-templates>` and
:ref:`TypoScript <t3start:typoscript>`.

This chapter is based on the following steps:
This chapter assumes the following:

* A Composer-based TYPO3 installation, at least version 13.4.
* You have installed a
`Generate a site package of type "Site Package Tutorial" <https://docs.typo3.org/permalink/t3sitepackage:minimal-design>`_,
including the example page tree loaded in `Create initial pages <https://docs.typo3.org/permalink/t3sitepackage:typo3-backend-create-initial-pages>`_.
* You have familiarized yourself with `Asset handling in TYPO3 <https://docs.typo3.org/permalink/t3sitepackage:assets-theme>`_
(CSS, JavaScript, design related images, ...)
* You are familiar with `Asset handling in TYPO3 <https://docs.typo3.org/permalink/t3sitepackage:assets-theme>`_
(CSS, JavaScript, design related images, etc)

After this tutorial you have a better understanding of the example templates and
how to adjust them to your needs. You should also be able to create some
templates yourself.
After this tutorial you will have a better understanding of Fluid templates and
how to customize them to your needs. You should also be able to create some
Fluid templates yourself.

If you prefer to start with a pure HTML template and build all templates
step by step, you can alternatively have a look a :ref:`fluid-templates-scratch`.
If you prefer to start with an HTML template and build it up to a Fluid template
step by step, have a look at :ref:`fluid-templates-scratch`.

.. contents:: Topics covered in this chapter

Expand All @@ -40,22 +40,22 @@ step by step, you can alternatively have a look a :ref:`fluid-templates-scratch`
The page view
=============

The Fluid templates for the whole page have to be configured via TypoScript.
The Fluid templates that we will use to output the frontend pages have to be configured via TypoScript.

In the example site package that was `Generated for you <https://docs.typo3.org/permalink/t3sitepackage:minimal-design>`_
the according TypoScript can be found in file
In the site package that was `Generated for you <https://docs.typo3.org/permalink/t3sitepackage:minimal-design>`_,
the TypoScript configuration can be found in
:file:`packages/my_site_package/Configuration/Sets/SitePackage/TypoScript/page.typoscript`:

.. literalinclude:: /CodeSnippets/my_site_package/Configuration/Sets/SitePackage/TypoScript/page.typoscript
:caption: packages/my_site_package/Configuration/Sets/SitePackage/TypoScript/page.typoscript
:linenos:
:emphasize-lines: 3,6

Line 3 defines that Fluid templates should be used for the page by using the
TypoScript object `PAGEVIEW <https://docs.typo3.org/permalink/t3tsref:cobj-pageview>`_.
Line 3 defines that Fluid templates should be configured using the
`PAGEVIEW <https://docs.typo3.org/permalink/t3tsref:cobj-pageview>`_ TypoScript object .

In line 6 the default path to the page view templates is defined. The definition
could be extended in line 7 by a setting later own. For now assume all Fluid
Line 6 defines the default path to the page view templates. We can add further
paths to the definition in line 7 with a site setting later on. For now assume all Fluid
templates for the page can be found in folder
:path:`packages/my_site_package/Resources/Private/PageView`.

Expand All @@ -65,78 +65,76 @@ The default page template
=========================

Unless a different page layout is chosen, `PAGEVIEW <https://docs.typo3.org/permalink/t3tsref:cobj-pageview>`_
expects the main template of the page in file :file:`PageView/Pages/Default.html` within
the defined folder (:path:`packages/my_site_package/Resources/Private/PageView`).
expects the main template of the page to be :file:`PageView/Pages/Default.html` in
the folder :path:`packages/my_site_package/Resources/Private/PageView` (the path
that we defined above).

Let us have a look at this template now:
Let's have a look at this default page template:

.. literalinclude:: /CodeSnippets/my_site_package/Resources/Private/PageView/Pages/Default.html
:caption: packages/my_site_package/Resources/Private/PageView/Pages/Default.html
:linenos:
:emphasize-lines: 1,2,4

* In line 1 the `Layout ViewHelper <f:layout> <https://docs.typo3.org/permalink/t3viewhelper:typo3fluid-fluid-layout>`_
is defined to load a layout template from folder :path:`PageView/Layouts`. The file
must have the same name of the templated, followed by `.html`, therefore
file :file:`packages/my_site_package/Resources/Private/PageView/Layouts/PageLayout.html`
is loaded as layout.
* Line 2 starts a new section with name "Main", using the
loads a layout template from the :path:`PageView/Layouts` folder. The layout
file is referred to by name, with an `.html` on the end. The layout file here is
:file:`packages/my_site_package/Resources/Private/PageView/Layouts/PageLayout.html`.
* Line 2 starts a section called "Main", using the
`Section ViewHelper <f:section> <https://docs.typo3.org/permalink/t3viewhelper:typo3fluid-fluid-section>`_.
* In Line 4 and 7 partial templates are loaded from :path:`Partials`. They follow
the same naming scheme like the Layout and are therefore located in
files :file:`Documentation/CodeSnippets/my_site_package/Resources/Private/PageView/Partials/Content.html`
and :file:`Documentation/CodeSnippets/my_site_package/Resources/Private/PageView/Partials/Stage.html`.
To do this they use the `Render ViewHelper <f:render> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-render>`_.
* Lines 4 and 7 load partial templates from the :path:`Partials` folder. They follow
the same naming scheme as the layout: they are located in
:file:`packages/my_site_package/Resources/Private/PageView/Partials/Content.html`
and :file:`packages/my_site_package/Resources/Private/PageView/Partials/Stage.html`.
The partials are loaded with the `Render ViewHelper <f:render> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-render>`_.

.. _layout-template:

The Fluid layout template
=========================

The outer most HTML that is needed for all different page layouts is usually
defined in a layout template:
The outermost HTML on a page/pages is defined by a layout template:

.. literalinclude:: /CodeSnippets/my_site_package/Resources/Private/PageView/Layouts/PageLayout.html
:caption: /CodeSnippets/my_site_package/Resources/Private/PageView/Layouts/PageLayout.html
:linenos:
:emphasize-lines: 5

The layout template takes care of loading assets like CSS and JavaScript that
are needed on all pages, using the `Asset collector <https://docs.typo3.org/permalink/t3coreapi:asset-collector>`_.
The layout template takes care of loading assets that
are needed on all pages, like CSS and JavaScript. It uses the `Asset collector <https://docs.typo3.org/permalink/t3coreapi:asset-collector>`_.

To configure the asset collector, the `Asset.css ViewHelper <f:asset.css> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-asset-css>`_
and `Asset.script ViewHelper <f:asset.script> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-asset-script>`_
are used.
The asset collector is configured using the `Asset.css ViewHelper <f:asset.css> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-asset-css>`_
and `Asset.script ViewHelper <f:asset.script> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-asset-script>`_.

The layout also renders sections that need to be defined with the
`Section ViewHelper <f:section> <https://docs.typo3.org/permalink/t3viewhelper:typo3fluid-fluid-section>`_
in the page template. In line 5 the section is rendered, which is defined in line
2-10 of the "Default" page template. It is possible to define several sections
and to define optional sections. We do not demonstrate that here.
Also, the layout template renders sections using a
`Section ViewHelper <f:section> <https://docs.typo3.org/permalink/t3viewhelper:typo3fluid-fluid-section>`_.
The sections are defined in the page template. The "Main" section in line 5
is defined in lines 2-10 of the "Default" page template. It is possible to define
optional sections (not shown here).

The layout template also loads some more partials, for example to display
Our layout template also loads some partials, for example, to display the
menu and the footer.

.. _page-html-structure:

Outer most HTML structure (body, head)
======================================
Outermost HTML structure (body, head)
=====================================

The outer most HTML structure is usually not handled by your custom templates. It
can be configured via the TypoScript configuration of the
The outermost HTML is not usually handled in Fluid templates. It
is configured via TypoScript configuration of the
`PAGE <https://docs.typo3.org/permalink/t3tsref:object-type-page>`_ object.

For example you can use option :ref:`shortcutIcon <t3tsref:confval-page-shortcuticon>`
to load a favicon, :ref:`meta <t3tsref:confval-page-meta>` to define meta tags,
or add tags to the body tag using :ref:`bodyTagAdd <t3tsref:confval-page-bodytagadd>`.
For example, you can use the :ref:`shortcutIcon <t3tsref:confval-page-shortcuticon>`
option to load a favicon, :ref:`meta <t3tsref:confval-page-meta>` to define meta tags,
and :ref:`bodyTagAdd <t3tsref:confval-page-bodytagadd>` to add tags to the body tag.

The page object, including examples is described in detail in the TypoScript
reference, chapter `Configure the PAGE in TypoScript <https://docs.typo3.org/permalink/t3tsref:guide-page>`_.
The page object, including examples, is described in detail in the TypoScript
reference. See `Configure the PAGE in TypoScript <https://docs.typo3.org/permalink/t3tsref:guide-page>`_.

.. _partial-template:

The footer: Example for a partial template
==========================================
The footer: Example of a partial template
=========================================

In the :ref:`layout template <layout-template>` the following partial was loaded:

Expand All @@ -145,22 +143,22 @@ In the :ref:`layout template <layout-template>` the following partial was loaded
:linenos:
:emphasize-lines: 5-7,11

Line 5 uses the `Link.page ViewHelper <f:link.page> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-link-page>`_
to link to the start page, which is the same like the root page and found in the
variable `{site.rootPageId}`.
Line 5 uses a `Link.page ViewHelper <f:link.page> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-link-page>`_
to link to the start page. The start page is the same as the root page and is found in the
`{site.rootPageId}` variable.

The variable `{site}` is automatically provided by the
`PAGEVIEW <https://docs.typo3.org/permalink/t3tsref:cobj-pageview>`_. All
available variables are described in the TypoScript Reference, section
`PAGEVIEW <https://docs.typo3.org/permalink/t3tsref:cobj-pageview>`_ TypoScript object. All
variables are described in the TypoScript Reference. See
`Default variables in Fluid templates <https://docs.typo3.org/permalink/t3tsref:cobj-pageview-data>`_.

Line 6 uses the `Image ViewHelper <f:image> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-image>`_
Line 6 uses an `Image ViewHelper <f:image> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-image>`_
to display a logo in the footer. The path to the logo and its alt tag are
defined in the settings definition. More about this in chapter
`Setting definition <https://docs.typo3.org/permalink/t3sitepackage:settings-definitions-yaml-constants>`_.
defined in the site package settings definitions. See
`Setting definitions <https://docs.typo3.org/permalink/t3sitepackage:settings-definitions-yaml-constants>`_.

In line 11 yet another partial is included. This partial displays a menu in the
footer. More about this topic in chapter :ref:`Configure the menus <main-menu-creation>`.
Line 11 adds another partial. This partial displays a menu in the
footer. See :ref:`Configuring the menus <main-menu-creation>`.

.. _fluid-templates-next-steps:

Expand Down