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>

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

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

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

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[].
• 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.

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

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

Currently, there is no clean way to solve this due to limitations of Fluid's parser. This would need a bigger rewrite, which is not yet feasible because of other more pressing issues. However, there are workarounds that might be applicable in your use case.

<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" />
<div
    x-data="{
        test: null,
        init() {
            test = 'foo';
        }
    }"
>
    <f:comment>Only necessary to fix parser issue</f:comment>
    {test}
</div>

<f:variable name="color" value="red" />
<style>
    @media (min-width: 1000px) <f:format.raw>{</f:format.raw>
        p {
            background-color: {color};
        }
    }
</style>

<f:alias map="{l: '{', r: '}'}">
    var values = {};
    <f:for each="{items}" as="item">
        if (!values[{item.key}]) { values[{item.key}] = {}; }
        values[{item.key}][values[{item.key}].length] = {l} label: "{item.description} ({item.short})", value: {item.id} {r};
    </f:for>
</f:alias>

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:cache.warmup variables="{foo: bar}">
   Template code depending on {foo} variable which is not
   assigned when warming up Fluid's caches. {foo} is only
   assigned if the variable does not already exist and the
   assignment only happens if Fluid is in warmup mode.
</f:cache.warmup>

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]

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'}}" />

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

Example

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

first

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>

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)

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: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}" />

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

<f:section name="mySection">
    <ul>
        <f:for each="{myMenu}" as="menuItem">
            <li>
                {menuItem.text}
                <f:if condition="{menuItem.subItems}">
                    <f:render section="mySection" arguments="{myMenu: menuItem.subItems}" />
                </f:if>
            </li>
        </f:for>
    </ul>
   </f:section>
   <f:render section="mySection" arguments="{myMenu: menu}" />

<ul>
    <li>menu1
        <ul>
          <li>menu1a</li>
          <li>menu1b</li>
        </ul>
    </li>
[...]
(depending on the value of {menu})

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

the content of the partial "somePartial".
Using the reserved keyword "_all", all available variables will be passed along to the partial

<f:render delegate="My\Special\ParsedTemplateImplementation" arguments="{_all}" />

Examples

<f:replace value="Hello World" search="World" replace="Fluid" />

Hello Fluid

<f:replace value="Hello World" search="{0: 'World', 1: 'Hello'}" replace="{0: 'Fluid', 1: 'Hi'}" />

Hi Fluid

<f:replace value="Hello World" replace="{'World': 'Fluid', 'Hello': 'Hi'}" />

Hi Fluid

Examples

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

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

<f:section name="mySection">
   <ul>
        <f:for each="{myMenu}" as="menuItem">
             <li>
               {menuItem.text}
               <f:if condition="{menuItem.subItems}">
                   <f:render section="mySection" arguments="{myMenu: menuItem.subItems}" />
               </f:if>
             </li>
        </f:for>
   </ul>
</f:section>
<f:render section="mySection" arguments="{myMenu: menu}" />

<ul>
    <li>menu1
        <ul>
            <li>menu1a</li>
            <li>menu1b</li>
        </ul>
    </li>
[...]
(depending on the value of {menu})

Usage of f:spaceless

<f:spaceless>
    <div>
        <div>
            <div>text

    text</div>
        </div>
    </div>
</f:spaceless>

Output:

<div><div><div>text

text</div></div></div>

Examples

<f:variable name="result"><f:split value="1,5,8" separator="," /></f:variable>

{0: '1', 1: '5', 2: '8'}

<f:variable name="result"><f:split separator="-">1-5-8</f:split></f:variable>

{0: '1', 1: '5', 2: '8'}

<f:variable name="result"><f:split value="1,5,8" separator="," limit="2" /></f:variable>

{0: '1', 1: '5,8'}

Examples

<f:switch expression="{person.gender}">
    <f:case value="male">Mr.</f:case>
    <f:case value="female">Mrs.</f:case>
    <f:defaultCase>Mr. / Mrs.</f:defaultCase>
</f:switch>

"Mr.", "Mrs." or "Mr. / Mrs." (depending on the value of {person.gender})

Implementation

An ExpressionNode is always one PHP class. Where you place it is completely up to you - but to have the class actually be detected and used by Fluid, it needs to be added to the rendering context by calling setExpressionNodeTypes().

In Fluid's default RenderingContext, the following code is responsible for returning expression node class names:

/**
 * List of class names implementing ExpressionNodeInterface
 * which will be consulted when an expression does not match
 * any built-in parser expression types.
 *
 * @var string
 */
protected $expressionNodeTypes = [
    'TYPO3Fluid\\Fluid\\Core\\Parser\\SyntaxTree\\Expression\\CastingExpressionNode',
    'TYPO3Fluid\\Fluid\\Core\\Parser\\SyntaxTree\\Expression\\MathExpressionNode',
    'TYPO3Fluid\\Fluid\\Core\\Parser\\SyntaxTree\\Expression\\TernaryExpressionNode',
];

/**
 * @return string
 */
public function getExpressionNodeTypes()
{
    return $this->expressionNodeTypes;
}

You may or may not want the listed expression nodes included, but if you change the available expression types you should of course document this difference about your implementation.

The following class is the math ExpressionNode from Fluid itself which detects the {a + 1} and other simple mathematical operations. To get this behavior, we need a (relatively simple) regular expression and one method to evaluate the expression while being aware of the rendering context (which stores all variables, controller name, action name etc).

<?php
namespace TYPO3Fluid\Fluid\Core\Parser\SyntaxTree\Expression;

use TYPO3Fluid\Fluid\Core\Rendering\RenderingContextInterface;

class MathExpressionNode extends AbstractExpressionNode
{
    /**
    * Pattern which detects the mathematical expressions with either
    * object accessor expressions or numbers on left and right hand
    * side of a mathematical operator inside curly braces, e.g.:
    *
    * {variable * 10}, {100 / variable}, {variable + variable2} etc.
    */
    public static string $detectionExpression = '/
        (
            {                                # Start of shorthand syntax
                \s*                          # Allow whitespace before expression
                (?:                          # Math expression is composed of...
                    [_a-zA-Z0-9\.]+(?:[\s]*[*+\^\/\%\-]{1}[\s]*[_a-zA-Z0-9\.]+)+   # Various math expressions left and right sides with any spaces
                    |(?R)                    # Other expressions inside
                )+
                \s*                          # Allow whitespace after expression
            }                                # End of shorthand syntax
        )/x';

    public static function evaluateExpression(RenderingContextInterface $renderingContext, string $expression, array $matches): int|float
    {
        // Split the expression on all recognized operators
        $matches = [];
        preg_match_all('/([+\-*\^\/\%]|[_a-zA-Z0-9\.]+)/s', $expression, $matches);
        $matches[0] = array_map('trim', $matches[0]);
        // Like the BooleanNode, we dumb down the processing logic to not apply
        // any special precedence on the priority of operators. We simply process
        // them in order.
        $result = array_shift($matches[0]);
        $result = static::getTemplateVariableOrValueItself($result, $renderingContext);
        $result = ($result == (int)$result) ? (int)$result : (float)$result;
        $operator = null;
        $operators = ['*', '^', '-', '+', '/', '%'];
        foreach ($matches[0] as $part) {
            if (in_array($part, $operators)) {
                $operator = $part;
            } else {
                $part = static::getTemplateVariableOrValueItself($part, $renderingContext);
                $part = ($part == (int)$part) ? (int)$part : (float)$part;
                $result = self::evaluateOperation($result, $operator, $part);
            }
        }
        return $result;
    }

    // ...
}

Taking from this example class the following are the rules you must observe:

1. You must either subclass the AbstractExpressionNode class or implement the ExpressionNodeInterface (subclassing the right class will automatically implement the right interface).
2. You must provide the class with an exact property called public static $detectionExpression which contains a string that is a perl regular expression which will result in at least one match when run against expressions you type in Fluid. It is vital that the property be both static and public and have the right name - it is accessed without instantiating the class.
3. The class must have a public static function evaluateExpression taking exactly the arguments above - nothing more, nothing less. The method must be able to work in a static context (it is called this way once templates have been compiled).
4. The evaluateExpression method may return any value type you desire, but like ViewHelpers, returning a non-string-compatible value implies that you should be careful about how you then use the expression; attempting to render a non-string-compatible value as a string may cause PHP warnings.

TemplateView

A fairly standard View implementation. The default object expects TemplatePaths as constructor argument and has a handful of utility methods like $view->assign('variablename', 'value');. Custom View types can be implemented by subclassing the default class - but in order to avoid problems, make sure you also call the original class' constructor method.

Creating a custom View allows you to change just a few aspects, mainly about composition: which implementations of TemplatePaths the View requires, if it needs a custom ViewHelperResolver, if it must have some default variables, if it should have a default cache, etc.

TemplatePaths

In the default TemplatePaths object included with Fluid we provide a set of conventions for resolving the template files that go into rendering a Fluid template - the templates themselves, plus partials and layouts.

You should use the default TemplatePaths object if:

1. You are able to place your template files in folders that match the Fluid conventions, including the convention of subfolders named the same as your controllers.
2. You are able to provide the template paths that get used as an array with which TemplatePaths can be initialized.
3. Or you are able to individually set each group of paths.
4. You are able to rely on standard format handling (format simply being the file extension of template files).

And you should replace the TemplatePaths with your own subclass if:

1. You answered no to any of the above.
2. You want to be able to deliver template content before parsing, from other sources than files.
3. You want the resolving of template files for controller actions to happen in a different way.
4. You want to create other (caching-) identifiers for your partials, layouts and templates than defaults.

Whether you use your own class or the default, the TemplatePaths instance must be provided as first argument for the View.

RenderingContext

The rendering context is the state object in Fluid's rendering process. By default, it contains references to all other objects that are relevant in the rendering process, such as the TemplateParser, the TemplateCompiler, a StandardVariableProvider or the TemplatePaths mentioned above. It also contains information about the current template context, somewhat confusingly stored in controllerName and controllerAction due to the MVC origins of Fluid.

Since Fluid 2.14, it is also possible to add arbitrary data to the rendering context, which obsoletes most cases where you would have to override the rendering context implementation in Fluid integrations:

$myCustomState = new \Vendor\Package\MyClass::class();
$view->getRenderingContext()->setAttribute(\Vendor\Package\MyClass::class, $myCustomState);

If at all possible, it should be avoided to use a custom RenderingContext implementation. However, currently it might still be necessary for some cases, for example if you want to replace the default implementation of one of the other dependencies, such as the StandardVariableProvider.

With further refactoring, we try to provide better ways for these use cases in the future.

FluidCache

The caching of Fluid templates happens by compiling the templates to PHP files which execute much faster than a parsed template ever could. These compiled templates can only be stored if a FluidCacheInterface-implementing object is provided. Fluid provides one such caching implementation: the SimpleFileCache which just stores compiled PHP code in a designated directory.

Should you need to store the compiled templates in other ways you can implement FluidCacheInterface in your caching object.

Whether you use your own cache class or the default, the FluidCache must be passed as third parameter for the View or it must be assigned using :php:`$view->getRenderingContext()->setCache($cacheInstance)` before calling :php:`$view->render()`.

ViewHelperInvoker

The ViewHelperInvoker is a class dedicated to validating current arguments of and if valid, calling the ViewHelper's render method. It is the primary API to execute a ViewHelper from within PHP code. The default object supports the arguments added via initializeArguments() and registerArgument() on the ViewHelper and provides all additional arguments via handleAdditionalArguments() to the ViewHelper class. By default, the ViewHelper implementations throw an exception, but this handling can be overwritten, as demonstrated by AbstractTagBasedViewHelper.

You should replace the ViewHelperInvoker if:

1. You must support different ways of calling ViewHelpers such as alternative setArguments names.
2. You wish to change the way the invoker uses and stores ViewHelper instances, for example to use an internal cache.
3. You wish to change the way ViewHelper arguments are validated, for example changing the Exceptions that are thrown.
4. You wish to perform processing on the output of ViewHelpers, for example to remove XSS attempts according to your own rules.

ViewHelperResolver

In Fluid most of your options for extending the language - for example, adding new ways to format strings, to make special condition types, custom links and such - are implemented as ViewHelpers. These are the special classes that are called using for example <f:format.htmlentities>{somestring}</f:format.htmlentities>.

A ViewHelper is essentially referenced by the namespace and the path to the ViewHelper, in this case f being the namespace and format.htmlentities being the path.

The ViewHelperResolver is the class responsible for turning these two pieces of information into an expected class name and when this class is resolved, to retrieve from it the arguments you can use for each ViewHelper.

You should use the default ViewHelperResolver if:

1. You can rely on the default way of turning a namespace and path of a ViewHelper into a class name.
2. You can rely on the default way ViewHelpers return the arguments they support.
3. You can rely on instantiation of ViewHelpers happening through a simple new $class().

You should replace the ViewHelperResolver if:

1. You answered no to any of the above.
2. You want to make ViewHelper namespaces available in templates without importing.
3. You want to use the dependency injection of your framework to resolve and instantiate ViewHelper objects.
4. You want to change which class is resolved from a given namespace and ViewHelper path, for example allowing you to add your own ViewHelpers to the default namespace or replace default ViewHelpers with your own.
5. You want to change the argument retrieval from ViewHelpers or you want to manipulate the arguments (for example, giving them a default value, making them optional, changing their data type).

The default ViewHelperResolver can be replaced on the rendering context by calling $renderingContext->setViewHelperResolver($resolverInstance);.

TemplateProcessor

While custom TemplatePaths also allows sources of template files to be modified before they are given to the TemplateParser, a custom TemplatePaths implementation is sometimes overkill - and has the drawback of completely overruling the reading of template file sources and making it up to the custom class how exactly this processing happens.

In order to allow a more readily accessible and flexible way of pre-processing template sources and affect key aspects of the parsing process, a TemplateProcessorInterface is provided. Implementing this interface and the methods it designates allows your class to be passed to the TemplateView and be triggered every time a template source is parsed, right before parsing starts:

$myTemplateProcessor = new MyTemplateProcessor();
$myTemplateProcessor->setDoMyMagicThing(true);
$templateView->setTemplateProcessors([
    $myTemplateProcessor
]);

The registration method requires an array - this is to let you define multiple processors without needing to wrap them in a single class as well as reuse validation/manipulation across frameworks and only replace the parts that need to be replaced.

This makes the method preProcessSource($templateSource) be called on this class every time the TemplateParser is asked to parse a Fluid template. Modifying the source and returning it makes that new template source be used. Inside the TemplateProcessor method you have access to the TemplateParser and ViewHelperResolver instances which the View uses.

The result is that TemplateProcessor instances are able to, for example:

• Validate template sources and implement reporting/logging of errors in a framework.
• Fix things like character encoding issues in template sources.
• Process Fluid code from potentially untrusted sources, for example doing XSS removals before parsing.
• Extract legacy namespace definitions and assign those to the ViewHelperResolver for active use.
• Extract legacy escaping instruction headers and assign those to the TemplateParser's Configuration instance.
• Enable the use of custom template code in file's header, extracted and used by a framework.

Note again: these same behaviors are possible using a custom TemplatePaths implementation - but even with such a custom implementation this TemplateProcessor pattern can still be used to manipulate/validate the sources coming from TemplatePaths, providing a nice way to decouple paths resolving from template source processing.

2.15

• Deprecation: First parameter of method TYPO3Fluid\Fluid\View\TemplatePaths->__construct() is deprecated. The Constructor will be removed with Fluid v5.
• Deprecation: Method TYPO3Fluid\Fluid\View\TemplatePaths->fillFromConfigurationArray() has been marked as deprecated. It will log a deprecation level error message when called in Fluid v4.
• Deprecation: Method TYPO3Fluid\Fluid\View\TemplatePaths->fillDefaultsByPackageName() has been marked as deprecated. It will log a deprecation level error message when called in Fluid v4.
• Deprecation: Method TYPO3Fluid\Fluid\View\TemplatePaths->ensureAbsolutePaths() has been marked as deprecated. It will log a deprecation level error message when called in Fluid v4.
• Deprecation: Method TYPO3Fluid\Fluid\View\TemplatePaths->extractPathArrays() has been marked as deprecated. It will log a deprecation level error message when called in Fluid v4.
• Deprecation: Method TYPO3Fluid\Fluid\View\TemplatePaths->getPackagePath() has been marked as deprecated. It will log a deprecation level error message when called in Fluid v4.
• Deprecation: Method TYPO3Fluid\Fluid\View\TemplatePaths->toArray() has been marked as deprecated. It will log a deprecation level error message when called in Fluid v4.
• Deprecation: Constant TYPO3Fluid\Fluid\View\TemplatePaths::DEFAULT_TEMPLATES_DIRECTORY has been marked as deprecated and will be removed in Fluid v5.
• Deprecation: Constant TYPO3Fluid\Fluid\View\TemplatePaths::DEFAULT_LAYOUTS_DIRECTORY has been marked as deprecated and will be removed in Fluid v5.
• Deprecation: Constant TYPO3Fluid\Fluid\View\TemplatePaths::DEFAULT_PARTIALS_DIRECTORY has been marked as deprecated and will be removed in Fluid v5.
• Deprecation: Trait TYPO3Fluid\Fluid\Core\ViewHelper\Traits\CompileWithRenderStatic has been marked as deprecated. It will log a deprecation level error message when called in Fluid v4. It will be removed in Fluid v5.
• Deprecation: Trait TYPO3Fluid\Fluid\Core\ViewHelper\Traits\CompileWithContentArgumentAndRenderStatic has been marked as deprecated. It will log a deprecation level error message when called in Fluid v4. It will be removed in Fluid v5.
• Deprecation: Static method renderStatic() on ViewHelpers that don't use TYPO3Fluid\Fluid\Core\ViewHelper\Traits\CompileWithRenderStatic or TYPO3Fluid\Fluid\Core\ViewHelper\Traits\CompileWithContentArgumentAndRenderStatic have been marked as deprecated. They will log a deprecation level error message when called in Fluid v4. renderStatic() will no longer be called in Fluid v5.
• Deprecation: Variable names true, false and null will log a deprecation level error message because these identifiers will become a Fluid language feature with v4.

2.14

• Deprecation: Method TYPO3Fluid\Fluid\View\AbstractTemplateView::initializeRenderingContext() has been marked as deprecated. It will be removed in Fluid v4. Migration path is to call the rendering context directly via TYPO3Fluid\Fluid\View\AbstractTemplateView::getRenderingContext()->getViewHelperVariableContainer()->setView()
• Deprecation: Method TYPO3Fluid\Fluid\View\AbstractTemplateView::setCache() has been marked as deprecated. It will be removed in Fluid v4. Migration path is to call the rendering context directly via TYPO3Fluid\Fluid\View\AbstractTemplateView::getRenderingContext()->setCache()
• Deprecation: Method TYPO3Fluid\Fluid\View\AbstractTemplateView::getTemplatePaths() has been marked as deprecated. It will be removed in Fluid v4. Migration path is to call the rendering context directly via TYPO3Fluid\Fluid\View\AbstractTemplateView::getRenderingContext()->getTemplatePaths()
• Deprecation: Method TYPO3Fluid\Fluid\View\AbstractTemplateView::getViewHelperResolver() has been marked as deprecated. It will be removed in Fluid v4. Migration path is to call the rendering context directly via TYPO3Fluid\Fluid\View\AbstractTemplateView::getRenderingContext()->getViewHelperResolver()
• Deprecation: Method TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper->overrideArgument() has been marked as deprecated. It will log a deprecation level error message when called in Fluid v4. It will be removed in Fluid v5. TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper->registerArgument() now no longer throws an exception if an argument is already defined, so calls to TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper->overrideArgument() can be replaced with TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper->registerArgument().

2.12

• Deprecation: Method TYPO3Fluid\Fluid\Core\ViewHelper\AbstractTagBasedViewHelper->registerUniversalTagAttributes() has been marked as deprecated. It will log a deprecation level error message when called in Fluid v4. It will be removed in Fluid v5. Arbitrary tags are automatically added by AbstractTagBasedViewHelper, single ViewHelpers find such arguments in $this->additionalArguments when the call to registerUniversalTagAttributes() is removed.
• Deprecation: Method TYPO3Fluid\Fluid\Core\ViewHelper\AbstractTagBasedViewHelper->registerTagAttribute() has been marked as deprecated. It will log a deprecation level error message when called in Fluid v4. It will be removed in Fluid v5. Arbitrary tags are automatically added by AbstractTagBasedViewHelper, single ViewHelpers find such arguments in $this->additionalArguments when the call to registerUniversalTagAttributes() is removed. Alternatively, arguments registered using registerArgument() can be found in $this->arguments.
• Deprecation: Test abstracts TYPO3Fluid\Fluid\Tests\BaseTestCase and TYPO3Fluid\Fluid\Tests\UnitTestCase have been marked as deprecated and will be removed in Fluid v4. Extend PHPUnit\Framework\TestCase directly.

2.9

• Deprecation: Class TYPO3Fluid\Fluid\Core\Compiler\ViewHelperCompiler has been obsoleted and marked as deprecated. It will be removed in Fluid v4.
• Deprecation: Exception TYPO3Fluid\Fluid\Core\Compiler\StopCompilingChildrenException has been obsoleted and marked as deprecated. It will be removed in Fluid v4.
• Deprecation: Trait TYPO3Fluid\Fluid\Core\ViewHelper\Traits\ParserRuntimeOnly has been obsoleted by inlining the code to consumers and marked as deprecated. It will be removed in Fluid v4.

2.8

• Deprecation: Method TYPO3Fluid\Fluid\Core\Parser\SyntaxTree\ObjectAccessorNode->getAccessors() is unused and has been marked as deprecated. It will be removed in Fluid v4.
• Deprecation: Unused public constant TYPO3Fluid\Fluid\Core\Compiler\TemplateCompiler::SHOULD_GENERATE_VIEWHELPER_INVOCATION has been marked as deprecated and will be removed in Fluid v4.
• Deprecation: Unused public constant TYPO3Fluid\Fluid\Core\Variables\StandardVariableProvider::ACCESSOR_ARRAY has been marked as deprecated and will be removed in Fluid v4.
• Deprecation: Unused public constant TYPO3Fluid\Fluid\Core\Variables\StandardVariableProvider::ACCESSOR_GETTER has been marked as deprecated and will be removed in Fluid v4.
• Deprecation: Unused public constant TYPO3Fluid\Fluid\Core\Variables\StandardVariableProvider::ACCESSOR_ASSERTER has been marked as deprecated and will be removed in Fluid v4.
• Deprecation: Unused public constant TYPO3Fluid\Fluid\Core\Variables\StandardVariableProvider::ACCESSOR_PUBLICPROPERTY has been marked as deprecated and will be removed in Fluid v4.
• Deprecation: Unused public static property TYPO3Fluid\Fluid\Core\Parser\Patterns::$SCAN_PATTERN_ESCAPINGMODIFIER has been marked as deprecated and will be removed in Fluid v4.

2.6

• Deprecation: Method TYPO3Fluid\Fluid\Core\ViewHelper\AbstractConditionViewHelper->evaluateCondition() has been marked as deprecated. It will be removed in Fluid v4. Use verdict() instead.

2.5

• Deprecation: Interface TYPO3Fluid\Fluid\Core\Parser\SyntaxTree\Expression\ParseTimeEvaluatedExpressionNodeInterface is unused and has been marked as deprecated. It will be removed in Fluid v4.

2.4