Creating a View 

Fluid comes with a bunch of PHP classes that allow you to open Fluid template files, assign variables to them and then render them to get the desired result. To get started, you need to be aware of TemplateView, the RenderingContext and TemplatePaths.

• The TemplateView is the "view part" in the Model-View-Controller pattern. It is the main API between your PHP application and the template file. Each TemplateView renders exactly one template file (which can have a layout file and can also include other templates, called partials).
• The RenderingContext is kind of self-describing: It contains all context necessary to render the template. At first, you might only use it to define the path to your Fluid template file via ...
• TemplatePaths, which is usually a sub-object of the rendering context. It provides multiple ways to define the location(s) to your template files.

To render a template file called MyTemplate.html, which is located in /path/to/templates/, you first create a TemplateView object:

$view = new \TYPO3Fluid\Fluid\View\TemplateView();

Then you can access the TemplatePaths and provide the location to your template file, for example like this:

$view->getRenderingContext()->getTemplatePaths()->setTemplateRootPaths(['/path/to/templates/']);

Finally, you can render the desired template:

$view->render('MyTemplate');

By default, .html is used as file extension. If you want to change this, you can specify a different format in TemplatePaths:

$view->getRenderingContext()->getTemplatePaths()->setFormat('xml');
$view->render('MyTemplate');

Which would then render MyTemplate.xml.

Assigning Variables 

To be able to access data available in your PHP script, you need to assign that data to your view as a variable:

$myData = obtainMyDataFromSomewhere();
$view->assign('myData', $myData);

You can also assign multiple variables at once:

$view->assignMultiple([
    'title' => $myTitle,
    'description' => $myDescription,
]);

Those variables can then be accessed in your template file:

<h1>{title}</h1>
<p>{description}</p>

See also the dedicated chapter about Variables.

Using ViewHelpers 

Within Fluid templates, it is possible to use some controll structures to implement simple logic. It is also possible to perform some data modification. Both is possible by using so-called ViewHelpers.

With the <f:if> ViewHelper, you can implement simple if-then-else logic, for example:

<f:if condition="{title}">
    <f:then>
        <h1>{title}</h1>
    </f:then>
    <f:else>
        <h1>Default Title</h1>
    </f:else>
</f:if>

With the <f:format.case> ViewHelper you can convert a variable to uppercase or lowercase letters:

<h1><f:format.case mode="upper">{title}</f:format.case></h1>

Which would result in an all-uppercase headline.

See also the dedicated chapter about ViewHelpers as well as the ViewHelper reference for more details.

Inspecting and Debugging Templates 

If you encounter a problem in your template or you just want to know what data is available, you can use the <f:debug> ViewHelper:

<f:debug>{myVariable}</f:debug>

If you want to get an overview of all available variables, you can use the special variable {_all}:

<f:debug>{_all}</f:debug>

Special _all Variable 

The special variable {_all} contains an array with all variables that are currently defined in your template. This can be helpful for debugging purposes, but also if you want to pass all variables to a partial:

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

However, be advised that this makes it more difficult to re-use partials, so it's recommend to only pass the variables that are actually needed in the partial.

Variable Scopes 

Each Fluid template, partial and section has its own variable scope. For templates, these variables are set via the PHP API, for partials and sections the <f:render> ViewHelper has a arguments argument to provide variables.

Inside templates, partials and sections there are two variable scopes: global variables and local variables. Local variables are created by ViewHelpers that provide additional variables to their child nodes. Local variables are only valid in their appropriate context and don't leak out to the whole template.

For example, <f:alias> and <f:for> create local variables:

<f:for each="{items}" as="item">
    <!-- {item} is valid here -->
</f:for>
<!-- {item} is no longer valid here -->

<f:alias map="{item: myObject.sub.item}">
    <!-- {item} is valid here -->
</f:for>
<!-- {item} is no longer valid here -->

If a global variable uses the same name as a local value, the state of the global value will be restored when the local variable is invalidated:

<f:variable name="item" value="global item" />
<!-- {item} is "global item" -->
<f:for each="{0: 'local item'}" as="item">
    <!-- {item} is "local item" -->
</f:for>
<!-- {item} is "global item" -->

If a variable is created in a local block, for example by using the <f:variable> ViewHelper, that variable is treated as a global variable, so it will leak out of the scope:

<f:for each="{0: 'first', 1: 'second'}" as="item">
    <f:variable name="lastItem" value="{item}" />
</f:for>
<!-- {lastItem} is "second" -->

If a global variable is created inside a local scope and uses the same name as a local variable, it will still leak out of the scope and will also be valid inside the scope:

<f:for each="{0: 'first', 1: 'second'}" as="item">
    <!-- {item} is "first" or "second" -->
    <f:variable name="item" value="overwritten" />
    <!-- {item} is "overwritten" -->
</f:for>
<!-- {item} is "overwritten" -->

The API 

Fluid uses a class called TemplatePaths which is part of the view's RenderingContext and can resolve and deliver template file paths and sources. In order to change the default paths you can set new ones in the TemplatePaths associated with your RenderingContext:

// Create your view
$view = new \TYPO3Fluid\Fluid\View\TemplateView();
// set up paths object with arrays of paths with files
$paths = $view->getRenderingContext()->getTemplatePaths();
$paths->setTemplateRootPaths(['/path/to/templates/']);
$paths->setLayoutRootPaths(['/path/to/layouts/']);
$paths->setPartialRootPaths(['/path/to/partials/']);

Note that paths are always defined as arrays. In the default TemplatePaths implementation, Fluid supports lookups in multiple template file locations - which is very useful if you are rendering template files from another package and wish to replace just a few template files. By adding your own template files path last in the paths arrays, Fluid will check those paths first.

Templates 

In Fluid, Templates can be referenced in two different ways:

• Directly by file path and filename
• Resolved using a controller name and action (and format)

Direct usage is of course done by simply setting the full path to the template file that must be rendered; no magic in that.

In an MVC (model-view-controller) context the latter can be used to implement a universal way to resolve the template files so you do not have to set the file path and filename for each file you want to render. In this case, Fluid will resolve template by using the pattern {$templateRootPath}/{$controllerName}/{$actionName}.{$format} with all of these variables coming directly from the TemplatePaths instance - which means that by filling the TemplatePaths instance with information about your MVC context you can have Fluid automatically resolve the paths of template files associated with controller actions.

Templates may or may not use a layout. The layout can be indicated by the use of <f:layout name="LayoutName" /> in the template source.

Fluid will behave slightly differently when a template uses a layout and when it does not:

• When no Layout is used, the template is rendered directly and will output everything not contained in an <f:section>
• When a Layout is used, the Template itself is not rendered directly. Instead, the Template defines any number of <f:section> containers which contain the pieces that will be rendered from the layout using <f:render>

You can choose freely between using a layout and not using one - even when rendering templates in an MVC context, some templates might use layouts and others might not. Whether or not you use layouts of course depends on the design you are trying to convey.

• An example Template without a Layout
• An example Template with a Layout and the Layout used by that Template

Layouts 

Layouts are as the name implies a layout for composing the individual bits of the design. When your design uses a shared HTML design with just smaller pieces being interchangeable (which most web applications do) your layout can contain the container HTML and the individual templates can define the smaller design bits that get used by the layout.

The template in this case defines a number of <f:section> containers which the layout renders with <f:render>. In application terms, the rendering engine switches to the layout when it detects one and renders it while preserving the template's context of controller name and action name.

• An example Layout and Template which uses it

Partials 

Partials are the smallest design bits that you can use when you need to have reusable bits that can be rendered from multiple templates, layouts or even other partials. To name a few types of design bits that make sense as partials:

• Address renderings
• Lists rendered from arrays
• Article metadata blocks
• Structured data markup

The trick with partials is they can expect a generically named but predictably structured object (such as an Address domain object instance, an array of string values, etc). When rendering the Partial, the data can then be picked from any source that fulfills the requirements. In the example of an Address, such an object might be found on both a Person and a Company, in which case we can render the same partial but with different sources:

• <f:render partial="Address" arguments="{address: person.address}" />
• <f:render partial="Address" arguments="{address: company.address}" />

The partial then expects the variable {address} with all the properties required to render an address; street, city, etc.

A partial may or may not contain <f:section>. If it does contain <f:section> containers, then the contents of those containers can be rendered anywhere, including inside the Partial itself, by <f:render partial="NameOfPartial" section="NameOfSection" />. Partials without sections can be rendered by just <f:render partial="NameOfPartial" /> (with or without arguments).

• An example of a partial template without sections
• An example of a partial template with sections

Argument Definitions 

Templates, layouts and partials can define requirements for variables by using the <f:argument> ViewHelper. It is possible to define a variable as required or optional. Also, a specific type can be required. If any of the constraints don't match the supplied data, an exception is thrown.

In effect, this allows you to define an API for template files, which improves both documentation and reusability of template files, especially partials.

How to use ViewHelpers 

ViewHelpers are special tags in the template which provide more complex functionality such as loops or special formatting of values. The functionality of a ViewHelper is implemented in PHP, and each ViewHelper has its own PHP class.

See the 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 built-in Fluid namespace:

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

Custom ViewHelpers use their own namespace, in this case blog:

<blog:myViewHelper argument1="something" />

The namespace needs to be registered explicitly, see the next section.

ViewHelpers can accept input values both from their tag content and from arguments, which are specified as tag attributes. The ViewHelper syntax is documented in Fluid ViewHelper Syntax.

Registering/importing ViewHelpers 

When you need to use third-party ViewHelpers in your templates, there are multiple equally valid options.

You can use the PHP API to register a namespace that should be available in all template files without further importing:

$view = new TemplateView();
$view->getRenderingContext()->getViewHelperResolver()
    ->addNamespace('foo', 'Vendor\\Foo\\ViewHelpers');

To make a namespace only available in one template file, the following syntax variants are possible:

<!-- xmlns variant -->
<html
    xmlns:foo="http://typo3.org/ns/Vendor/Foo/ViewHelpers"
    data-namespace-typo3-fluid="true"
>

<!-- inline variant -->
{namespace foo=Vendor\Foo\ViewHelpers}

Once you have registered/imported the ViewHelper collection, you can start using it in your templates via the namespace alias you used during registration (in this example: foo is the alias name).

Tag-based ViewHelpers 

Tag-based ViewHelpers are special ViewHelpers that extend a different base class called AbstractTagBasedViewHelper. The purpose of these special ViewHelpers is to generate a HTML tag based on the supplied arguments and content.

Tag-based ViewHelpers provide default arguments that help enhancing the generated HTML tag:

• An array of data-* attributes can be provided via the data argument
• An array of aria-* attributes can be provided via the aria argument
• An array of additional HTML attributes can be provided via the additionalAttributes argument
• You can also supply arbitrary arguments that don't need to be defined by the ViewHelper, which will be added to the generated HTML tag automatically

Example:

<my:viewHelper
    data="{
        foo: 'data foo',
        bar: 'data bar',
    }"
    aria="{
        label: 'my label',
    }"
    additionalAttributes="{
        'my-attribute': 'my attribute value',
    }"
    another-attribute="my other value"
>
    content
</my:viewHelper>

Assuming that the ViewHelper is configured to create a <div> tag, this would be the result:

<div
    data-foo="data foo"
    data-bar="data bar"
    aria-label="my label"
    my-attribute="my attribute value"
    another-attribute="my other value"
>
    content
</div>

<my:viewHelper async="{true}" />
Result: <div async="async" />

<my:viewHelper async="{false}" />
Result: <div />

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

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

<f:variable name="myEmptyString" value="" />
<my:viewHelper async="{myEmptyString}" />
Result: <div />

Condition ViewHelpers 

Condition ViewHelpers are another special type of ViewHelper that allow to check for certain conditions within a template. They extend from a different base class called AbstractConditionViewHelper.

All condition ViewHelpers have in common that a then and one or multiple else clauses can be defined. There are multiple ways to do this, and almost all combinations imaginable are possible.

The generic and most used condition ViewHelper is <f:if>.

<!-- then and else -->
<f:if condition="{myVar} == 'test'" then="variable is test" else="variable is something else" />
{f:if(condition: '{myVar} == \'test\'', then: 'variable is test', else: 'variable is something else')}

<!-- only then -->
<f:if condition="{myVar} == 'test'" then="variable is test" />
{f:if(condition: '{myVar} == \'test\'', then: 'variable is test')}

<!-- only else -->
<f:if condition="{myVar} == 'test'" else="variable is something else" />
{f:if(condition: '{myVar} == \'test\'', else: 'variable is something else')}

<!-- only then -->
<f:if condition="{myVar} == 'test'">
    variable is test
</f:if>

<!-- then and else -->
<f:if condition="{myVar} == 'test'">
    <f:then>variable is test</f:then>
    <f:else>variable is something else</f:else>
</f:if>

<!-- only else -->
<f:if condition="{myVar} == 'test'">
    <f:else>variable is something else</f:else>
</f:if>

<!-- multiple else-if -->
<f:if condition="{myVar} == 'test'">
    <f:then>variable is test</f:then>
    <f:else if="{myVar} == 'foo'">variable is foo</f:else>
    <f:else if="{myVar} == 'bar'">variable is bar</f:else>
    <f:else>variable is something else</f:else>
</f:if>

<!-- The variable will contain the result of the condition as boolean -->
<f:variable
    name="isEitherTestOrFoo"
    value="{f:if(condition: '{myVar} == \'test\' || {myVar} == \'foo\'')}"
/>

<!-- This example combines two custom condition ViewHelpers to a larger condition -->
<f:if condition="{my:customCondition(value: variableToCheck)} || {my:otherCondition(value: variableToCheck)}">
    ...
</f:if>

<!-- disabled attribute is set if either no first name or no last name is set -->
<my:tagBased
    disabled="{f:if(condition: '!{firstName} || !{lastName}')}"
/>

Understanding ViewHelpers 

All built-in ViewHelpers are documented in the ViewHelper Reference. If you want to learn more about a specific ViewHelper or if you are using a custom ViewHelper that isn't documented, you can take a look at the ViewHelper source code, written in PHP.

Each ViewHelper has a corresponding PHP file, which contains a class that describes the ViewHelper's arguments as well as its behavior in the template. Such classes are usually placed in the Vendor\Package\ViewHelpers PHP namespace (where Vendor and Package are placeholders for actual values) and follow the following naming convention:

• f:format.raw results from the PHP class TYPO3Fluid\Fluid\ViewHelpers\Format\RawViewHelper
• f:render results from the PHP class TYPO3Fluid\Fluid\ViewHelpers\RenderViewHelper
• mypkg:custom.specialFormat results from the PHP class My\Package\ViewHelpers\Custom\SpecialFormatViewHelper, assuming you added xmlns:mpkg="http://typo3.org/ns/My/Package/ViewHelpers" or an alternative namespace registration (see above).

Note that these rules only apply to normal ViewHelpers. For Components, different rules apply.

The arguments a ViewHelper supports will be verbosely registered in the initializeArguments() function of each ViewHelper class. Inspect this method to see the names, types, descriptions, required flags and default values of all attributes. An example argument definition looks like this:

public function initializeArguments() {
    $this->registerArgument('myArgument', 'boolean', 'If true, makes ViewHelper do foobar', false, false);
}

Which translated to human terms means that we:

• Register an argument named myArgument
• Specify that it must be a boolean value or an expression resulting in a boolean value (see Boolean conditions). Other valid types are integer, string, float, array, object, DateTime and other class names. The array of syntax can also be used, for example string[] or Vendor\Package\MyClass[]. Multiple type options (= union types) can be specified by separating them with a |, for example array|string.
• Describe the argument's behavior in simple terms.
• Define that the argument is not required (the 4th argument is false).
• Set a default value of false (5th argument), if the argument is not provided when calling the ViewHelper.

The ViewHelper itself would then be callable like this:

<mypkg:custom.specialFormat myArgument="{true}">{someVariable}</mypkg:custom.specialFormat>

What the ViewHelper does with its input values is determined by the render() method in the ViewHelper class.

Basic Setup 

Before templates can be used as components, an initial setup process is necessary: A ComponentCollection class is required, which allows you to define which template folder contains your component templates. Fluid comes with a base implementation in AbstractComponentCollection that already covers the most common use cases. However, it is also possible to customize the component context, such as providing global settings that should be available in all component templates.

A basic implementation looks like this:

namespace Vendor\MyPackage\Components;

use TYPO3Fluid\Fluid\Core\Component\AbstractComponentCollection;
use TYPO3Fluid\Fluid\View\TemplatePaths;

final class ComponentCollection extends AbstractComponentCollection
{
    public function getTemplatePaths(): TemplatePaths
    {
        $templatePaths = new TemplatePaths();
        $templatePaths->setTemplateRootPaths([
            'path/to/Components/',
        ]);
        return $templatePaths;
    }
}

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

$templatePaths->setTemplateRootPaths([
    ExtensionManagementUtility::extPath('my_sitepackage', 'Resources/Private/Components'),
]);

Defining Components 

The default implementation in AbstractComponentCollection specifies that each component template needs to be placed in a separate folder. The purpose of this decision is that related asset files (such as CSS or JS) can be placed right next to the component's template, which fosters a modular frontend architecture and enables easier refactoring.

Check out Alternative Folder Structure if you want to adjust this.

The <my:atom.button> component thus would be defined in path/to/Components/Atom/Button/Button.html like this:

<f:argument name="variant" type="string" optional="{true}" default="primary" />

<button class="myButton myButton--{variant}">
    <f:slot />
</button>

The <f:slot> ViewHelper can be used to access the children of the component tag.

Using Components 

Once the ComponentCollection class exists and the component template has been created, it can be imported into any Fluid template and component tags can be used:

<html
    xmlns:my="http://typo3.org/ns/Vendor/MyPackage/Components/ComponentCollection"
    data-namespace-typo3-fluid="true"
>

<my:atom.button variant="secondary">
    Button label
</my:atom.button>

Of course this works with all alternatives for importing namespaces.

This example would result in the following rendered HTML:

<button class="myButton myButton--secondary">
    Button label
</button>

$GLOBALS['TYPO3_CONF_VARS']['SYS']['fluid']['namespaces']['my'] = [
    \Vendor\MySitepackage\Components\ComponentCollection::class,
];

<html
    xmlns:my="http://typo3.org/ns/Vendor/MyPackage/Components/ComponentCollection"
    data-namespace-typo3-fluid="true"
>

<my:atom.button variant="secondary">
    <my:atom.icon name="submit" />
    Button label
</my:atom.button>

<html
    xmlns:my="http://typo3.org/ns/Vendor/MyPackage/Components/ComponentCollection"
    data-namespace-typo3-fluid="true"
>

<my:atom.button variant="secondary" icon="submit">
    Button label
</my:atom.button>

<html
    xmlns:my="http://typo3.org/ns/Vendor/MyPackage/Components/ComponentCollection"
    data-namespace-typo3-fluid="true"
>

<f:argument name="variant" type="string" optional="{true}" default="primary" />
<f:argument name="icon" type="string" optional="{true}" />

<button class="myButton myButton--{variant}">
    <f:if condition="{icon}">
        <my:atom.icon name="{icon}" />
    </f:if>
    <f:slot />
</button>

Providing Context 

Sometimes it might be helpful to provide some global settings to all components within one component collection. One common use case could be to provide design tokens from a JSON file to your components.

AbstractComponentCollection provides getAdditionalVariables(), which allows you to do just that:

namespace Vendor\MyPackage\Components;

use TYPO3Fluid\Fluid\Core\Component\AbstractComponentCollection;

final class ComponentCollection extends AbstractComponentCollection
{
    // Runtime cache to prevent reading/parsing the JSON file multiple times
    // this is not mandatory, but increases performance with multiple components
    private ?array $designTokens = null;

    // ...

    public function getAdditionalVariables(string $viewHelperName): array
    {
        $this->designTokens ??= json_decode(file_get_contents('path/to/designTokens.json'), true);
        return [
            'designTokens' => $this->designTokens,
        ];
    }
}

In your component templates you would then be able to access those tokens:

<f:argument name="color" type="string" optional="{true}" default="brand" />

<div style="background-color: {designTokens.colors.{color}}"></div>

Allowing Arbitrary Arguments 

By default, components only accept arguments that are defined explicitly via the <f:argument> ViewHelper. However, there might be use cases where you would like to accept arbitrary arguments.

This is possible by defining additionalArgumentsAllowed() in your ComponentCollection implementation (in this example for all components in the collection):

namespace Vendor\MyPackage\Components;

use TYPO3Fluid\Fluid\Core\Component\AbstractComponentCollection;

final class ComponentCollection extends AbstractComponentCollection
{
    // ...

    protected function additionalArgumentsAllowed(string $viewHelperName): bool
    {
        return true;
    }
}

The following call of the button component would then be valid:

<html
    xmlns:my="http://typo3.org/ns/Vendor/MyPackage/Components/ComponentCollection"
    data-namespace-typo3-fluid="true"
>

<my:atom.button something="my text">
    Button label
</my:atom.button>

In the component, {something} would be available as an additional variable.

Alternative Folder Structure 

If you want to define an alternative folder structure to the default {componentName}/{componentName}.html, you can do so by providing a custom implementation of resolveTemplateName() in your ComponentCollection. The following example skips the additional folder per component:

namespace Vendor\MyPackage\Components;

use TYPO3Fluid\Fluid\Core\Component\AbstractComponentCollection;

final class ComponentCollection extends AbstractComponentCollection
{
    // ...

    public function resolveTemplateName(string $viewHelperName): string
    {
        $fragments = array_map(ucfirst(...), explode('.', $viewHelperName));
        return implode('/', $fragments);
    }
}

<my:atom.button> will then be resolved to path/to/Components/Atom/Button.html.

Accessing variables 

Variables in Fluid can be accessed with the following braces {} syntax:

<h1>{title}</h1>

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

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

$product->getName()
$product->isName()
$product->hasName()
$product->name

{myArray.{myIndex}}

Reserved variable names 

The following variable names are reserved and must not be used:

• _all
• true
• false
• null

Objects and arrays 

Within a ViewHelper call, arrays (with numeric keys) and object structures can be defined inline:

<f:variable name="myArray" value="{0: 'first item', 1: 'second item'}" />

<f:variable name="myObject" value="{abc: 'first item', def: 'second item'}" />

<f:variable name="myOtherObject" value="{'abc 123': 'first item', 'def 456': 'second item'}" />

These can also be nested and indented:

<f:variable name="myArrayOfObjects" value="{
    0: {label: 'first item'},
    1: {label: 'second item'},
}" />

Trailing commas are valid syntax and are recommended to create cleaner diffs in version control systems.

Type casting 

The as expression can be used to convert variables to a different type. For example, {myPossiblyArray as array} will ensure that {myPossiblyArray} is accessed as an array even if it is of a different type such as null, which is useful if you are passing a value to a ViewHelper like <f:for> that requires an array as input. Other supported types for casting are: integer, boolean, string, float and DateTime.

If you use as array on a string that contains comma-separated values, the string is split at each comma, similar to PHP's explode function.

Math expressions 

Fluid supports basic math operations. For myNumber = 6, the following expressions result in:

{myNumber + 3} <!-- result: 9 -->
{myNumber - 3} <!-- result: 3 -->
{myNumber * 3} <!-- result: 18 -->
{myNumber / 3} <!-- result: 2 -->
{myNumber % 3} <!-- result: 0 -->
{myNumber ^ 3} <!-- result: 216 -->

Ternary expressions 

Fluid supports the ternary operator for variables, allowing you to switch between two variables based on the value of a variable. For static values, like a string, this is not supported.

{checkVariable ? thenVariable : elseVariable}

If {checkVariable} evaluates to true, variable {thenVariable} is used, otherwise variable {elseVariable} is used.

Escaping behavior in inline syntax 

At a certain nesting level, single quotes ' required for the inline syntax need to be escaped with a backslash:

<f:render partial="MyPartial" arguments="{
    myArgument: '{f:format.trim(value: \'{f:format.case(mode: \\\'upper\\\', value: \\\'{myVariable}\\\')}\')}',
}" />

While escaping cannot be avoided in all cases, alternatives should always be preferred to improve the readability of templates. Depending on the use cases, there are different approaches to achieve this.

{f:format.case(mode: 'upper', value: myVariable)}

{myVariable -> f:format.case(mode: 'upper') -> f:format.trim()}

Avoiding syntax collision with JS and CSS 

While it is generally advisable to avoid inline JavaScript and CSS code within Fluid templates, sometimes it may be unavoidable. This can lead to collisions between Fluid's inline or variable syntax and the curly braces {} syntax characters used in JavaScript and CSS.

There are two approaches how these collisions can be avoided:

<div data-value="{f:format.json(value: {foo: 'bar', bar: 'baz'})}">

<script>
let data = {f:format.json(value: {foo: 'bar', bar: 'baz'}) -> f:format.raw()};

<f:variable name="test" value="bar" />
<![CDATA[
<div
    x-data="{
        test: null,
        init() {
            test = 'foo';
        }
    }"
>
    {{{test}}}
</div>
]]>

<f:variable name="color" value="red" />
<style>
<![CDATA[
    @media (min-width: 1000px) {
        p {
            background-color: {{{color}}};
        }
    }
]]>
</style>

<f:variable name="countries" value="{
    0: {key: 'de', name: 'Germany', short: 'DE'},
    1: {key: 'us', name: 'United States of America', short: 'US'},
}" />
<script>
<![CDATA[
    const settings = {
        countries: {{{countries -> f:format.json() -> f:format.raw()}}},
    };
]]>
</script>

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 condition argument of the <f:if> ViewHelper.

1. The expression can be a variable, which is evaluated as follows:

   • Number: Evaluates to true if it is not 0.
   • Array: Evaluates to true if it contains at least one element.

2. The expression can be a statement consisting of: term1 operator term2, for example {variable} > 3.

   • The operator can be one of the following: >, >=, <, <=, ==, ===, !=, !==, or %.
3. The previous expressions can be combined with || (logical OR) or && (logical 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>

Boolean literals 

You can use the boolean literals {true} and {false} in ViewHelper calls. This works both in tag and inline syntax:

<f:render section="MySection" optional="{true}" />

{f:render(section: 'MySection', optional: true)}

If a ViewHelper argument is defined as boolean, it is also possible to provide values of different types, which will then be implicitly converted to a boolean:

<f:render section="MySection" optional="1" />

This can be used to remain compatible to Fluid 2, which did not support boolean literals in all cases.

Tag syntax 

The tag syntax works just like HTML or XML. Tags can either be self-closing or can have a content, which can include other HTML tags or ViewHelper calls.

<!-- self-closing -->
<f:constant name="\Vendor\Package\Class::CONSTANT" />

<!-- text content -->
<f:format.case mode="upper">lowercase</f:format.case>

<!-- other ViewHelpers as content -->
<f:switch expression="{myVariable}">
    <f:case value="foo">Variable is foo</f:case>
    <f:case value="bar">Variable is bar</f:case>
    <f:defaultCase>Variable is something else</f:defaultCase>
</f:switch>

<!-- Nested format ViewHelpers -->
<f:format.trim>
    <f:replace search="foo" replace="bar">
        <f:format.case mode="upper">
            {myString}
        </f:format.case>
    </f:replace>
</f:format.trim>

Inline syntax 

The inline syntax works using curly braces {}. Most ViewHelpers can also be used with the inline syntax, although the syntax might get more complicated depending on the use case.

{f:constant(name: '\Vendor\Package\Class::CONSTANT')}

{f:format.case(value: 'lowercase', mode: 'upper')}

{myVariable -> f:format.case(mode: 'upper')}

ViewHelpers that operate on a singular input value can usually be chained, which can make templates more readable:

{myString -> f:format.case(mode: 'upper') -> f:replace(search: 'foo', replace: 'bar') -> f:format.trim()}

The inline syntax can also be indented and can contain trailing commas and whitespace:

{f:render(
    partial: 'MyPartial',
    arguments: {
        foo: 'bar',
    },
)}

ViewHelper syntax comparison 

Depending on the situation, it might be better to use the inline syntax instead of the tag syntax and vice versa. Here is a more complex example that shows where the inline syntax is still possible, but might make things more complicated:

<f:variable name="myArray" value="{0: 'foo', 1: '', 2: 'bar'}" />
<f:for each="{myArray}" as="item">
    <f:if condition="{item}">
        <f:render section="MySection" arguments="{item: item}" />
    </f:if>
</f:for>

And its inline syntax variant:

<f:variable name="myArray" value="{0: 'foo', 1: '', 2: 'bar'}" />
{f:render(section:'MySection', arguments: {item: item}) -> f:if(condition: item) -> f:for(each: myArray, as: 'item')}

Please note that, in chained inline notation, the f:if ViewHelpers should not use their usual then or else attributes, as they would directly output their value and thus break the chain!

ViewHelper namespaces 

There are two syntax variants to import a ViewHelper namespace into a template. In the following examples, blog is the namespace available within the Fluid template and MyVendor\BlogExample\ViewHelpers is the PHP namespace to import into Fluid.

By default, the f namespace is predefined by Fluid. Depending on your setup, additional global namespaces, defined directly via the ViewHelperResolver, might be available.

<html
    xmlns:blog="http://typo3.org/ns/Myvendor/MyExtension/ViewHelpers"
    data-namespace-typo3-fluid="true"
>
</html>

{namespace blog=MyVendor\BlogExample\ViewHelpers}

Examples 

<f:cache.disable />

{f:cache.disable()}

<f:cache.disable>
   Some output or Fluid code
</f:cache.disable>

Examples 

<f:if condition="{var}">Is always evaluated also when compiled</f:if>
<f:cache.static>
    <f:if condition="{othervar}">
        Will only be evaluated once and this output will be
        cached as a static string with no logic attached.
        The compiled template will not contain neither the
        condition ViewHelperNodes or the variable accessor
        that are used inside this node.
    </f:if>
</f:cache.static>

<f:if condition="{var}">Also evaluated; is outside static node</f:if>

Examples 

<f:format.case>Some Text with miXed case</f:format.case>

SOME TEXT WITH MIXED CASE

<f:format.case mode="capital">someString</f:format.case>

SomeString

Examples 

<f:format.cdata>{string}</f:format.cdata>

<![CDATA[(Content of {string} without any conversion/escaping)]]>

<f:format.cdata value="{string}" />

<![CDATA[(Content of {string} without any conversion/escaping)]]>

{string -> f:format.cdata()}

<![CDATA[(Content of {string} without any conversion/escaping)]]>

Examples 

<f:format.htmlspecialchars>{text}</f:format.htmlspecialchars>

Text with & " ' < > * replaced by HTML entities (htmlspecialchars applied).

{text -> f:format.htmlspecialchars(encoding: 'ISO-8859-1')}

Text with & " ' < > * replaced by HTML entities (htmlspecialchars applied).

Examples 

{someArray -> f:format.json()}

{f:format.json(value: {foo: 'bar', bar: 'baz'})}

{f:format.json(value: {0: 'bar', 1: 'baz'}, forceObject: true)}

Examples 

<f:format.nl2br>{text_with_linebreaks}</f:format.nl2br>

{text_with_linebreaks -> f:format.nl2br()}

Examples 

<f:format.number>423423.234</f:format.number>

<f:format.number decimals="1" decimalSeparator="," thousandsSeparator=".">
    423423.234
</f:format.number>

Examples 

<f:format.printf arguments="{number: 362525200}">%.3e</f:format.printf>

3.625e+8

<f:format.printf arguments="{0: 3, 1: 'Kasper'}">%2$s is great, TYPO%1$d too. Yes, TYPO%1$d is great and so is %2$s!</f:format.printf>

Kasper is great, TYPO3 too. Yes, TYPO3 is great and so is Kasper!

<f:format.printf arguments="{1: 'TYPO3'}">We love %s</f:format.printf>

We love TYPO3

{someText -> f:format.printf(arguments: {1: 'TYPO3'})}

We love TYPO3

Examples 

<f:format.raw>{string}</f:format.raw>

(Content of ``{string}`` without any conversion/escaping)

<f:format.raw value="{string}" />

(Content of ``{string}`` without any conversion/escaping)

{string -> f:format.raw()}

(Content of ``{string}`` without any conversion/escaping)

Examples 

<f:format.stripTags>Some Text with <b>Tags</b> and an &Uuml;mlaut.</f:format.stripTags>

<f:format.stripTags allowedTags="<p><span><div><script>">
    <p>paragraph</p><span>span</span><div>divider</div><iframe>iframe</iframe><script>script</script>
</f:format.stripTags>

<p>paragraph</p><span>span</span><div>divider</div>iframe<script>script</script>

{text -> f:format.stripTags()}

{text -> f:format.stripTags(allowedTags: "<p><span><div><script>")}

Examples 

#<f:format.trim>   String to be trimmed.   </f:format.trim>#

#String to be trimmed.#

#<f:format.trim side="right">   String to be trimmed.   </f:format.trim>#

#   String to be trimmed.#

#<f:format.trim characters=" St.">   String to be trimmed.   </f:format.trim>#

#ring to be trimmed#

#{f:format.trim(value: my_variable)}#
#{my_variable -> f:format.trim()}#

Examples 

<f:format.urlencode>foo @+%/</f:format.urlencode>

{text -> f:format.urlencode()}

Examples 

<f:alias map="{x: 'foo'}">{x}</f:alias>

foo

<f:alias map="{x: foo.bar.baz, y: foo.bar.baz.name}">
    {x.name} or {y}
</f:alias>

[name] or [name]

General Example 

For the following partial:

<f:argument name="title" type="string" />
<f:argument name="tags" type="string[]" optional="{true}" />
<f:argument name="user" type="string" optional="{true}" default="admin" />

Title: {title}<br />
<f:if condition="{tags}">
  Tags: {tags -> f:join(separator: ', ')}<br />
</f:if>
User: {user}

The following render calls will be successful:

<!-- All arguments supplied -->
<f:render partial="MyPartial" arguments="{title: 'My title', tags: {0: 'tag1', 1: 'tag2'}, user: 'me'}" />
<!-- "user" will fall back to default value -->
<f:render partial="MyPartial" arguments="{title: 'My title', tags: {0: 'tag1', 1: 'tag2'}}" />
<!-- "tags" will be "null", "user" will fall back to default value -->
<f:render partial="MyPartial" arguments="{title: 'My title'}" />

The following render calls will result in an exception:

<!-- required "title" has not been supplied -->
<f:render partial="MyPartial" />
<!-- "user" has been supplied as array, not as string -->
<f:render partial="MyPartial" arguments="{title: 'My title', user: {firstName: 'Jane', lastName: 'Doe'}}" />

Union Types 

An argument can allow multiple multiple types. In that case, the component's implementation needs to make sure that all possible variants are considered. This should be used sparingly since it can complicate the component's implementation code considerably.

<f:argument name="number" type="int|float" />
<f:argument name="object" type="Vendor\Package\MyObjectA|Vendor\Package\MyObjectB" />

Examples 

<f:ceil value="123.456" />

124

<f:ceil>123.456</f:ceil>

124

Examples 

Before
<f:comment>
    This is completely hidden.
    <f:debug>This does not get rendered</f:debug>
</f:comment>
After

Before
After

Examples 

{f:constant(name: 'PHP_INT_MAX')}

9223372036854775807
(Depending on CPU architecture).

{f:constant(name: '\Vendor\Package\Class::CONSTANT')}

{f:constant(name: '\Vendor\Package\Enum::CASE')}

Examples 

<f:variable name="myArray" value="{0: 'Hello', 1: 'World'}" />

<f:contains value="Hello" subject="{myArray}">
    It Works!
</f:contains>

It Works!

<f:variable name="myString" value="Hello, World!" />

<f:contains value="Wo" subject="{myString}">
    It Works!
</f:contains>

It Works!

<f:variable name="myString" value="Hello, World!" />

<f:if condition="{someCondition} || {f:contains(value: 'Wo', subject: myString)}">
    It Works!
</f:if>

It Works!

Examples 

<f:count subject="{0:1, 1:2, 2:3, 3:4}" />

4

{objects -> f:count()}

10 (depending on the number of items in ``{objects}``)

Examples 

These examples could also be achieved using the "iteration" argument of the ForViewHelper.

<f:for each="{0:1, 1:2, 2:3, 3:4}" as="foo">
    <f:cycle values="{0: 'foo', 1: 'bar', 2: 'baz'}" as="cycle">
        {cycle}
    </f:cycle>
</f:for>

foobarbazfoo

<ul>
    <f:for each="{0:1, 1:2, 2:3, 3:4}" as="foo">
        <f:cycle values="{0: 'odd', 1: 'even'}" as="zebraClass">
            <li class="{zebraClass}">{foo}</li>
        </f:cycle>
    </f:for>
</ul>

<ul>
    <li class="odd">1</li>
    <li class="even">2</li>
    <li class="odd">3</li>
    <li class="even">4</li>
</ul>

Examples 

{object -> f:debug(title: 'Custom title')}

all properties of {object} nicely highlighted (with custom title)

{object -> f:debug(typeOnly: true)}

the type or class name of {object}

Examples 

<f:if condition="{someCondition}">
    <f:else>
        condition was not true
    </f:else>
</f:if>

Everything inside the "else" tag is displayed if the condition evaluates to false.
Otherwise, nothing is outputted in this example.

Examples 

<f:variable name="myString" value="Hello, World!" />
<f:endsWith search="Hello" subject="{myString}">This will be rendered if variable "myString" ends with "World!"</f:endsWith>

This will be rendered if variable "myString" ends with "World!"

<f:variable name="condition" value="{false}" />
<f:variable name="myString" value="Hello, World!" />

<f:if condition="{condition} || {f:endsWith(search: 'World!', subject: myString)}">
It Works!
</f:if>

It Works!

Example 

<f:first value="{0: 'first', 1: 'second'}" />

first

Example 

<f:flatten value="{0: {0: '1', 1: '2'}, 1: {0: '3', 1: '4'}}" />

{0: '1', 1: '2', 2: '3', 3: '4'}

Examples 

<f:floor value="123.456" />

123

<f:floor>123.456</f:floor>

123

Examples 

<f:for each="{0:1, 1:2, 2:3, 3:4}" as="foo">{foo}</f:for>

1234

<ul>
    <f:for each="{fruit1: 'apple', fruit2: 'pear', fruit3: 'banana', fruit4: 'cherry'}"
        as="fruit" key="label"
    >
        <li>{label}: {fruit}</li>
    </f:for>
</ul>

<ul>
    <li>fruit1: apple</li>
    <li>fruit2: pear</li>
    <li>fruit3: banana</li>
    <li>fruit4: cherry</li>
</ul>

<ul>
    <f:for each="{0:1, 1:2, 2:3, 3:4}" as="foo" iteration="fooIterator">
        <li>Index: {fooIterator.index} Cycle: {fooIterator.cycle} Total: {fooIterator.total}{f:if(condition: fooIterator.isEven, then: ' Even')}{f:if(condition: fooIterator.isOdd, then: ' Odd')}{f:if(condition: fooIterator.isFirst, then: ' First')}{f:if(condition: fooIterator.isLast, then: ' Last')}</li>
    </f:for>
</ul>

<ul>
    <li>Index: 0 Cycle: 1 Total: 4 Odd First</li>
    <li>Index: 1 Cycle: 2 Total: 4 Even</li>
    <li>Index: 2 Cycle: 3 Total: 4 Odd</li>
    <li>Index: 3 Cycle: 4 Total: 4 Even Last</li>
</ul>

Default Fragment Example 

If the following template Text.html:

<f:argument name="title" type="string" />

<div class="textComponent">
    <h2>{title}</h2>
    <div class="textComponent__content">
        <f:slot />
    </div>
</div>

is rendered with the following component call:

<my:text title="My title">
    <f:fragment>
        <p>My first paragraph</p>
        <p>My second paragraph</p>
    </f:fragment>
</my:text>

it will result in the following output:

<div class="textComponent">
    <h2>My title</h2>
    <div class="textComponent__content">
        <p>My first paragraph</p>
        <p>My second paragraph</p>
    </div>
</div>

Multiple Named Slots 

If the following template TextMedia.html:

<f:argument name="title" type="string" />

<div class="textMediaComponent">
    <h2>{title}</h2>
    <div class="textMediaComponent__media">
        <f:slot name="media" />
    </div>
    <div class="textMediaComponent__content">
        <f:slot name="content" />
    </div>
</div>

is rendered with the following component call:

<my:textMedia title="My title">
    <f:fragment name="media">
        <img src="path/to/image.jpg" alt="..." />
    </f:fragment>
    <f:fragment name="content">
        <p>My first paragraph</p>
        <p>My second paragraph</p>
    </f:fragment>
</my:textMedia>

it will result in the following output:

<div class="textMediaComponent">
    <h2>My title</h2>
    <div class="textMediaComponent__media">
        <img src="path/to/image.jpg" alt="..." />
    </div>
    <div class="textMediaComponent__content">
        <p>My first paragraph</p>
        <p>My second paragraph</p>
    </div>
</div>

Examples 

<f:groupedFor each="{0: {name: 'apple', color: 'green'}, 1: {name: 'cherry', color: 'red'}, 2: {name: 'banana', color: 'yellow'}, 3: {name: 'strawberry', color: 'red'}}"
    as="fruitsOfThisColor" groupBy="color"
>
    <f:for each="{fruitsOfThisColor}" as="fruit">
        {fruit.name}
    </f:for>
</f:groupedFor>

apple cherry strawberry banana

<ul>
    <f:groupedFor each="{0: {name: 'apple', color: 'green'}, 1: {name: 'cherry', color: 'red'}, 2: {name: 'banana', color: 'yellow'}, 3: {name: 'strawberry', color: 'red'}}" as="fruitsOfThisColor" groupBy="color" groupKey="color">
        <li>
            {color} fruits:
            <ul>
                <f:for each="{fruitsOfThisColor}" as="fruit" key="label">
                    <li>{label}: {fruit.name}</li>
                </f:for>
            </ul>
        </li>
    </f:groupedFor>
</ul>

<ul>
    <li>green fruits
        <ul>
            <li>0: apple</li>
        </ul>
    </li>
    <li>red fruits
        <ul>
            <li>1: cherry</li>
        </ul>
        <ul>
            <li>3: strawberry</li>
        </ul>
    </li>
    <li>yellow fruits
        <ul>
            <li>2: banana</li>
        </ul>
    </li>
</ul>

Fluid Boolean Rules / Conditions: 

A condition is evaluated as a boolean value, so you can use any boolean argument, like a variable. Alternatively, you can use a full boolean expression. The entered expression is evaluated as a PHP expression. You can combine multiple expressions via && (logical AND) and || (logical OR).

An expression can also be prepended with the ! ("not") character, which will negate that expression.

Have a look into the Fluid section of the "TYPO3 Explained" Documentation for more details about complex conditions.

Boolean expressions have the following form:

is true variant: {variable}:

<f:if condition="{foo}">
    Will be shown if foo is truthy.
</f:if>

or is false variant: !{variable}:

<f:if condition="!{foo}">
    Will be shown if foo is falsy.
</f:if>

or comparisons with expressions:

XX Comparator YY

Comparator is one of: ==, !=, <, <=, >, >= and % The % operator (modulo) converts the result of the operation to boolean.

XX and YY can be one of:

• Number
• String
• Object Accessor (object.property)
• Array
• a ViewHelper

<f:if condition="{rank} > 100">
    Will be shown if rank is > 100
</f:if>
<f:if condition="{rank} % 2">
    Will be shown if rank % 2 != 0.
</f:if>
<f:if condition="{rank} == {k:bar()}">
    Checks if rank is equal to the result of the ViewHelper "k:bar"
</f:if>
<f:if condition="{object.property} == 'stringToCompare'">
    Will result in true if {object.property}'s represented value
    equals 'stringToCompare'.
</f:if>

Examples 

<f:if condition="somecondition">
    This is being shown in case the condition matches
</f:if>

Everything inside the <f:if> tag is being displayed if the condition evaluates to true.

<f:if condition="somecondition">
    <f:then>
        This is being shown in case the condition matches.
    </f:then>
    <f:else>
        This is being displayed in case the condition evaluates to false.
    </f:else>
</f:if>

Everything inside the "then" tag is displayed if the condition evaluates to true.
Otherwise, everything inside the "else" tag is displayed.

{f:if(condition: someCondition, then: 'condition is met', else: 'condition is not met')}

The value of the "then" attribute is displayed if the condition evaluates to true.
Otherwise, everything the value of the "else" attribute is displayed.

<f:if condition="{user.rank} > 100 && {user.type} == 'contributor'">
    <f:then>
        This is being shown in case both conditions match.
    </f:then>
    <f:else if="{user.rank} > 200 && ({user.type} == 'contributor' || {user.type} == 'developer')">
        This is being displayed in case the first block of the condition evaluates to true and any condition in
        the second condition block evaluates to true.
    </f:else>
    <f:else>
        This is being displayed when none of the above conditions evaluated to true.
    </f:else>
</f:if>

Depending on which expression evaluated to true, that value is displayed.
If no expression matched, the contents inside the final "else" tag are displayed.

Examples 

<f:join value="{0: '1', 1: '2', 2: '3'}" />

123

<f:join value="{0: '1', 1: '2', 2: '3'}" separator=", " />

1, 2, 3

<f:join value="{0: '1', 1: '2', 2: '3'}" separator=", " separatorLast=" and " />

1, 2 and 3

Example 

<f:last value="{0: 'first', 1: 'second'}" />

second

Examples 

<f:layout name="main" />

Output:

(no output)

Examples 

<f:length value="Hello, World!" />

13

<f:length value="Hello, World!" encoding="UTF-8" />

13

{f:length(value: 'Hello, World!')}

13

Example 

<f:max value="{0: '1', 1: '2', 2: '3'}" />

Output:

3

Example 

<f:merge array="{0: 'a', 1: 'b'}" with="{1: 'x', 2: 'c'}" />

{0: 'a', 1: 'x', 2: 'c'}

<f:merge array="{foo: {bar: 'baz'}}" with="{foo: {qux: 'value'}}" recursive="true" />

{foo: {bar: 'baz', qux: 'value'}}

{f:variable(name: 'myArray', value: {foo: 1})}
{myArray -> f:merge(with: {bar: 2})}

{foo: 1, bar: 2}

Example 

<f:min value="{0: '1', 1: '2', 2: '3'}" />

Output:

1

Usage of f:or 

{f:variable(name:'fallback',value:'this is not the variable you\'re looking for')}
{undefinedVariable -> f:or(alternative:fallback)}

Usage of ternary operator 

In some cases (e.g. when you want to check for empty instead of null) it might be more handy to use a ternary operator instead of f:or

{emptyVariable ?: 'this is an alterative text'}

Examples 

<f:variable name="result"><f:range start="1" end="5" /></f:variable>

{0: 1, 1: 2, 2: 3, 3: 4, 4: 5}

<f:variable name="result" value="{f:range(start: 1, end: 5)}" />

{0: 1, 1: 2, 2: 3, 3: 4, 4: 5}

<f:variable name="result" value="{f:range(start: 5, end: 0)}" />

{0: 5, 1: 4, 2: 3, 3: 2, 4: 1, 5: 0}

<f:variable name="result" value="{f:range(start: 1, end: 6, step: 2)" />

{0: 1, 1: 3, 2: 5}

<f:variable name="result" value="{f:range(start: 5, end: 1, step: 2)" />

{0: 5, 1: 3, 2: 1}

Examples 

<f:render partial="SomePartial" arguments="{foo: someVariable}" />

the content of the partial "SomePartial". The content of the variable {someVariable} will be available in the partial as {foo}

<f:section name="someSection">This is a section. {foo}</f:section>
<f:render section="someSection" arguments="{foo: someVariable}" />