Fluid Templates

To understand the following section you need basic knowledge of the Fluid templating engine and TypoScript.

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", including the example page tree loaded in Create initial pages.
You are familiar with Asset handling in TYPO3 (CSS, JavaScript, design related images, etc)

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 an HTML template and build it up to a Fluid template step by step, have a look at Fluid Templates from Scratch.

Topics covered in this chapter

The page view

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

In the site package that was Generated for you, the TypoScript configuration can be found in packages/my_site_package/Configuration/Sets/SitePackage/TypoScript/page.typoscript:

        packages/my_site_package/Configuration/Sets/SitePackage/TypoScript/page.typoscript
    

page = PAGE
page {
  10 = PAGEVIEW
  10 {
    paths {
      0 = EXT:my_site_package/Resources/Private/PageView/
      10 = {$MySitePackage.template_path}
    }

    dataProcessing {
      # makes content elements available as {content} in Fluid template
      10 = page-content
    }
  }
  shortcutIcon = {$MySitePackage.favicon}
}

Line 3 defines that Fluid templates should be configured using the PAGEVIEW TypoScript object .

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 packages/my_site_package/Resources/Private/PageView.

The default page template

Unless a different page layout is chosen, PAGEVIEW expects the main template of the page to be PageView/Pages/Default.html in the folder packages/my_site_package/Resources/Private/PageView (the path that we defined above).

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

packages/my_site_package/Resources/Private/PageView/Pages/Default.html

<f:layout name="PageLayout"/>
<f:section name="Main">

    <f:render partial="Stage" arguments="{_all}"/>

    <div class="container">
        <f:render partial="Content" arguments="{records: content.main.records}"/>
    </div>

</f:section>

In line 1 the Layout ViewHelper <f:layout> loads a layout template from the PageView/Layouts folder. The layout file is referred to by name, with an .html on the end. The layout file here is packages/my_site_package/Resources/Private/PageView/Layouts/PageLayout.html.
Line 2 starts a section called "Main", using the Section ViewHelper <f:section>.
Lines 4 and 7 load partial templates from the Partials folder. They follow the same naming scheme as the layout: they are located in packages/my_site_package/Resources/Private/PageView/Partials/Content.html and packages/my_site_package/Resources/Private/PageView/Partials/Stage.html. The partials are loaded with the Render ViewHelper <f:render>.

The Fluid layout template

The outermost HTML on a page/pages is defined by a layout template:

        /CodeSnippets/my_site_package/Resources/Private/PageView/Layouts/PageLayout.html
    

<f:asset.css identifier="bootstrap" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" />
<f:asset.css identifier="main" href="EXT:my_site_package/Resources/Public/Css/main.css" />
<main>
    <f:render partial="Header" arguments="{_all}"/>
    <f:render section="Main"/>
    <f:render partial="Footer" arguments="{_all}"/>
</main>
<f:asset.script identifier="bootstrap" src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js" />
<f:asset.script identifier="main" src="EXT:my_site_package/Resources/Public/JavaScript/main.js" />

The layout template takes care of loading assets that are needed on all pages, like CSS and JavaScript. It uses the Asset collector.

The asset collector is configured using the Asset.css ViewHelper <f:asset.css> and Asset.script ViewHelper <f:asset.script>.

Also, the layout template renders sections using a Section ViewHelper <f: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).

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

Outermost HTML structure (body, head)

The outermost HTML is not usually handled in Fluid templates. It is configured via TypoScript configuration of the PAGE object.

For example, you can use the shortcutIcon option to load a favicon, meta to define meta tags, and bodyTagAdd to add tags to the body tag.

The page object, including examples, is described in detail in the TypoScript reference. See Configure the PAGE in TypoScript.

The footer: Example of a partial template

In the layout template the following partial was loaded:

/CodeSnippets/my_site_package/Resources/Private/PageView/Partials/Footer.html

<div class="container">
    <footer class="d-flex flex-wrap justify-content-between align-items-center py-3 my-4 border-top">
        <div class="col-md-4 d-flex align-items-center">

            <f:link.page pageUid="{site.rootPageId}" class="mb-3 me-2 mb-md-0 text-body-secondary text-decoration-none lh-1">
                <f:image src="{settings.MySitePackage.logo}" alt="{settings.MySitePackage.logo-alt}" height="24" class="bi" />
            </f:link.page>
            <span class="mb-3 mb-md-0 text-body-secondary">&copy; <f:format.date format="Y">now</f:format.date> {site.configuration.websiteTitle}</span>
        </div>

        <f:render partial="Navigation/FooterMenu.html" arguments="{_all}"/>
    </footer>
</div>

Line 5 uses a Link.page ViewHelper <f: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 TypoScript object. All variables are described in the TypoScript Reference. See Default variables in Fluid templates.

Line 6 uses an Image ViewHelper <f:image> to display a logo in the footer. The path to the logo and its alt tag are defined in the site package settings definitions. See Setting definitions.

Line 11 adds another partial. This partial displays a menu in the footer. See Configuring the menus.