Introduction to Fluid

Example Fluid snippet

This is how a simple Fluid snippet could look like:

<h4>This is your headline</h4>
<p>
    <f:if condition="{myExpression}">
        <f:then>
            {somevariable}
        </f:then>
        <f:else>
            {someothervariable}
        </f:else>
    </f:if>
</p>

The resulting HTML may look like this:

<h4>This is your headline</h4>
<p>This is the content of variable "somevariable"</p>

The above Fluid snippet contains:

ViewHelpers:

The XML elements that start with f: like <f:if> etc. are standard ViewHelpers. It is also possible to define custom ViewHelpers, for example <foo:bar foo="bar">. A corresponding file ViewHelpers/BarViewHelper.php with the methods initializeArguments and render contains the HTML generation logic. ViewHelpers are Fluid components which make a function call to PHP from inside of a template. TYPO3 adds some more ViewHelpers for TYPO3 specific functionality.

ViewHelpers can do simple processing such as remove spaces with the Spaceless ViewHelper <f:spaceless> ViewHelper or create a link as is done in the TYPO3 Fluid Viewhelper Link.page ViewHelper <f:link.page>.

Expressions, variables:

Fluid uses placeholders to fill content in specified areas in the template where the result is rendered when the template is evaluated. Content within braces (for example {somevariable}) can contain variables or expressions.

Conditions:

The conditions are supplied here by the If ViewHelper <f:if> ViewHelper.

Directory structure

In your extension, the following directory structure should be used for Fluid files:

This directory structure is the convention used by TYPO3. When using Fluid outside of TYPO3 you can use any folder structure you like.

If you are using Extbase controller actions in combination with Fluid, Extbase defines how files and directories should be named within these directories. Extbase uses sub directories located within the "Templates" directory to group templates by controller name and the filename of templates to correspond to a certain action on that controller.

If you don't use Extbase you can still use this convention, but it is not a requirement to use this structure to group templates into logical groups, such as "Page" and "Content" to group different types of templates.

In Fluid, the location of these paths is defined with \TYPO3Fluid\Fluid\Core\Rendering\RenderingContext->setTemplatePaths().

TYPO3 provides the possibility to set the paths using TypoScript.

<div class="header">
    <f:render section="Header" />
</div>
<div class="main">
    <f:render section="Main" />
</div>

<f:layout name="Default" />

<f:section name="Header">
    <!-- add header here ! -->
</f:section>

<f:section name="Main">
    <!-- add main content here ! -->
</f:section>

<b>Tags</b>:
<ul>
    <f:for each="{tags}" as="tag">
        <li>{tag}</li>
    </f:for>
</ul>

<f:render partial="Tags" arguments="{tags: post.tags}" />

Example: Using Fluid to create a theme for a site package

This example was taken from a theme created by the Site Package Builder and reduced to a very basic example.

Set the Fluid base path with TypoScript using the PAGEVIEW TypoScript object.

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
    }
  }
}

The template in file Pages/Default.html is automatically used whenever there is no specific template for the current Backend layout of the page.

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

</f:section>

It includes the layout Layouts/PageLayout.html. And uses partial Partials/Content.html to display its content.

It uses the partial Partials/Content.html to display its content.

<f:for each="{records}" as="record">
    <f:cObject
        typoscriptObjectPath="{record.mainType}"
        data="{record}"
        table="{record.mainType}"
    />
</f:for>

The template for a different backend layout will look similar, but has for example two columns:

<f:layout name="PageLayout"/>
<f:section name="Main">
    <div class="container">
        <div class="row">
            <div class="col-md-8">
                <f:render partial="Content" arguments="{records: content.main.records}"/>
            </div>
            <div class="col-md-4">
                <f:render partial="Content" arguments="{records: content.sidebar.records}"/>
            </div>
        </div>
    </div>
</f:section>

The page layout takes care of elements that are shared across all or most page types:

<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>