Fluid syntax

Variables

Assign a variable in PHP:

$this->view->assign('title', 'An example title');

Output it in a Fluid template:

<h1>{title}</h1>

The result:

<h1>An example title</h1>

In the template's HTML code, wrap the variable name into curly braces to output it.

Reserved variables in Fluid

Changed in version Fluid 4.0 / TYPO3 v13.3

Assigning variables of names true, false or null will throw an exception in Fluid v4.

Migration

EXT:my_extension/Classes/Controller/MyController.php (diff)

- $myView->assign('true', $something);
+ $myView->assign('myVariable', $something);

EXT:my_extension/Resources/Private/Templates/MyTemplate.html (diff)

- <f:variable name="false">Some value</f:variable>
- <div>{false}</div>
+ <f:variable name="myVariable">Some value</f:variable>
+ <div>{myVariable}</div>

Boolean values

New in version Fluid 4.0 / TYPO3 v13.3

The boolean literals {true} and {false} have been introduced.

You can use the boolean literals {true} and {false} to enable or disable properties of tag-based ViewHelpers:

<my:viewhelper async="{true}" />
Result: <tag async="async" />

<my:viewhelper async="{false}" />
Result: <tag />

Of course, any variable containing a boolean can be supplied as well:

<my:viewhelper async="{isAsync}" />

It is also possible to cast a string to a boolean

<my:viewhelper async="{myString as boolean}" />

For compatibility reasons empty strings still lead to the attribute being omitted from the tag.

<f:variable name="myEmptyString"></f:variable>
<my:viewhelper async="{myEmptyString}" />
Result: <tag />

Arrays and objects

Assign an array in PHP:

$this->view->assign('data', ['Low', 'High']);

Use the dot . to access array keys:

EXT:site_package/Resources/Private/Templates/SomeTemplate.html

<p>{data.0}, {data.1}</p>

This also works for object properties:

EXT:site_package/Classes/Controller/SomeController.php

$this->view->assign('product', $myProduct);

Use it like this:

EXT:site_package/Resources/Private/Templates/SomeTemplate.html

<p>{product.name}: {product.price}</p>

Accessing dynamic keys/properties

It is possible to access array or object values by a dynamic index:

EXT:site_package/Resources/Private/Templates/SomeTemplate.html

{myArray.{myIndex}}

ViewHelpers

ViewHelpers are special tags in the template which provide more complex functionality such as loops or generating links.

The functionality of the ViewHelper is implemented in PHP, every ViewHelper has its own PHP class.

See the Fluid ViewHelper Reference for a complete list of all available ViewHelpers.

Within Fluid, the ViewHelper is used as a special HTML element with a namespace prefix, for example the namespace prefix "f" is used for ViewHelpers from the Fluid namespace:

Fluid example with for ViewHelper

<f:for each="{results}" as="result">
   <li>{result.title}</li>
</f:for>

The "f" namespace is already defined, but can be explicitly specified to improve IDE autocompletion.

Fluid example with custom ViewHelper "custom" in namespace "blog":

EXT:blog_example/Resources/Private/Templates/SomeTemplate.html

<blog:custom argument1="something"/>

Here, we are using a custom ViewHelper within the namespace "blog". The namespace must be registered explicitly, see the next section.

Import ViewHelper namespaces

There are 3 ways to import ViewHelper namespaces in TYPO3. In all three examples blog is the namespace available within the Fluid template and MyVendor\BlogExample\ViewHelpers is the PHP namespace to import into Fluid.

Use an <html> tag with xmlns

EXT:blog_example/Resources/Private/Templates/SomeTemplate.html
```
<html
   xmlns:blog="http://typo3.org/ns/Myvendor/MyExtension/ViewHelpers"
   data-namespace-typo3-fluid="true"
>
</html>
```
Copied!
This is useful for various IDEs and HTML auto-completion. The <html> element itself will not be rendered if the attribute data-namespace-typo3-fluid="true" is specified.

The namespace is built using the fixed http://typo3.org/ns prefix followed by the vendor name, package name and the fixed ViewHelpers suffix.

Important

Do not use https://typo3.org (HTTPS instead of HTTP). Fluid would not be able to detect this namespace to convert it to PHP class name prefixes. Remember: This is a unique XML namespace, it does not need to contain a valid URI.
Local namespace import via curly braces {}-syntax

EXT:blog_example/Resources/Private/Templates/SomeTemplate.html
```
{namespace blog=MyVendor\BlogExample\ViewHelpers}
```
Copied!
Each of the rows will result in a blank line. Multiple import statements can go into a single or multiple lines.
Global namespace import

Fluid allows to register global namespaces. This is already done for typo3/cms-fluid and typo3fluid/fluid ViewHelpers. Therefore they are always available via the f namespace.

Custom ViewHelpers, for example for a site package, can be registered the same way. Namespaces are registered within $GLOBALS['TYPO3_CONF_VARS']['SYS']['fluid']['namespaces'] , for example:
EXT:mye_extension/ext_localconf.php
```
<?php

declare(strict_types=1);

use MyVendor\MyExtension\ViewHelpers;

defined('TYPO3') or die();

$GLOBALS['TYPO3_CONF_VARS']['SYS']['fluid']['namespaces']['myextension'] = [
    ViewHelpers::class,
];
```
Copied!

ViewHelper attributes

Simple

Variables can be inserted into ViewHelper attributes by putting them in curly braces:

EXT:site_package/Resources/Private/Templates/SomeTemplate.html

Now it is: <f:format.date format="{format}">{date}</f:format.date>

Fluid inline notation

Tip

There is an online converter from tag-based syntax to inline syntax: Fluid Converter

An alternative to the tag based notation used above is inline notation. For example, compare the 2 identical Fluid constructs:

EXT:my_extensions/Resources/Private/Templates/Something.html

<!-- tag based notation -->
<f:translate key="LLL:EXT:core/Resources/Private/Language/locallang_misc.xlf:bookmark_inactive"/>

<!-- inline notation -->
{f:translate(key: 'LLL:EXT:core/Resources/Private/Language/locallang_misc.xlf:bookmark_inactive')}

Tag based notation and inline notation can be freely mixed within one Fluid template.

Inline notation is often a better choice if HTML tags are nested, for example:

EXT:my_extensions/Resources/Private/Templates/Something.html

<!-- tag based notation -->
<span title="<f:translate key='LLL:EXT:core/Resources/Private/Language/locallang_misc.xlf:bookmark_inactive'/>">

<-- inline notation -->
<span title="{f:translate(key: 'LLL:EXT:core/Resources/Private/Language/locallang_misc.xlf:bookmark_inactive')}">

More complex example with chaining:

EXT:my_extensions/Resources/Private/Templates/Something.html

<!-- tag based notation -->
<f:format.padding padLength="40"><f:format.date format="Y-m-d">{post.date}</f:format.date></f:format.padding>

<!-- inline notation -->
{post.date -> f:format.date(format: 'Y-m-d') -> f:format.padding(padLength: 40)}

Boolean conditions

Boolean conditions are expressions that evaluate to true or false.

Boolean conditions can be used as ViewHelper arguments, whenever the datatype boolean is given, e.g. in the if ViewHelper condition argument.

The expression can be a variable which is evaluated as follows:
- number: evaluates to true, if > 0.
- array: evaluates to true if it contains at least one element
The expression can be a statement consisting of: term1 operator term2, for example {variable} > 3
- The operator can be one of >, >=, <, <=, ==, ===, !=, !== or %,
The previous expressions can be combined with || (or) or && (and).

Examples:

<f:if condition="{myObject}">
  ...
</f:if>

<f:if condition="{myNumber} > 3 || {otherNumber} || {somethingelse}">
   <f:then>
      ...
   </f:then>
   <f:else>
      ...
   </f:else>
</f:if>

<my:custom showLabel="{myString} === 'something'">
  ...
</my:custom>

Example using the inline notation:

<div class="{f:if(condition: blog.posts, then: 'blogPostsAvailable', else: 'noPosts')}">
  ...
</div>

Comments

If you want to completely skip parts of your template, you can make use of the Comment ViewHelper <f:comment>.

Changed in version 13.3

The content of the Comment ViewHelper <f:comment> is removed before parsing. It is no longer necessary to combine it with CDATA tags to disable parsing.

EXT:my_extension/Resources/Private/Templates/SomeTemplate.html

<f:comment>
    This will be ignored by the Fluid parser and will not appear in
    the source code of the rendered template
</f:comment>

You can also use the Comment ViewHelper <f:comment> to temporarily comment out some Fluid syntax while debugging:

EXT:my_extension/Resources/Private/Templates/SomeTemplate.html

<f:comment>
    <x:someBrokenFluid>
</f:comment>