Fluid Templates

To understand the following section you need basic knowledge about how to use the Fluid templating engine and TypoScript.

This chapter is based on the following steps:

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 have familiarized yourself with Asset handling in TYPO3 (CSS, JavaScript, design related images, ...)

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.

If you prefer to start with a pure HTML template and build all templates step by step, you can alternatively have a look a Fluid Templates from the Scratch.

Topics covered in this chapter

The page view

The Fluid templates for the whole page have to be configured via TypoScript.

In the example site package that was Generated for you the according TypoScript can be found in file 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 used for the page by using the TypoScript object PAGEVIEW.

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 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 in file PageView/Pages/Default.html within the defined folder (packages/my_site_package/Resources/Private/PageView).

Let us have a look at this template now:

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> is defined to load a layout template from folder PageView/Layouts. The file must have the same name of the templated, followed by .html, therefore 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 Section ViewHelper <f:section>.
In Line 4 and 7 partial templates are loaded from Partials. They follow the same naming scheme like the Layout and are therefore located in files Documentation/CodeSnippets/my_site_package/Resources/Private/PageView/Partials/Content.html and Documentation/CodeSnippets/my_site_package/Resources/Private/PageView/Partials/Stage.html. To do this they use the Render ViewHelper <f:render>.

The Fluid layout template

The outer most HTML that is needed for all different page layouts is usually defined in 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 like CSS and JavaScript that are needed on all pages, using the Asset collector.

To configure the asset collector, the Asset.css ViewHelper <f:asset.css> and Asset.script ViewHelper <f:asset.script> are used.

The layout also renders sections that need to be defined with the Section ViewHelper <f: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.

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

Outer most 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 PAGE object.

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

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

The footer: Example for 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 the Link.page ViewHelper <f:link.page> to link to the start page, which is the same like the root page and found in the variable {site.rootPageId}.

The variable {site} is automatically provided by the PAGEVIEW. All available variables are described in the TypoScript Reference, section Default variables in Fluid templates.

Line 6 uses the Image ViewHelper <f: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.

In line 11 yet another partial is included. This partial displays a menu in the footer. More about this topic in chapter Configure the menus.