Diving Into TYPO3 Fluid [50+ Tips]

TYPO3 Fluid - One of the unique frontend template engine of TYPO3 CMS! As a TYPO3 integrator or developer, you should have mastery of the TYPO3 Fluid template engine. In this blog, I want to share helpful tips & tricks of TYPO3 Fluid. Get ready!

Fluid is a powerful Open Source template engine system used in TYPO3, Neos CMS, and Flow PHP Framework. If you are a beginner, I highly recommend you read one of my popular blogs, How to Use TYPO3 Fluid? (Basic to Advanced Guide). In this blog, you will find TYPO3 Fluid hints from my personal experience and includes valuable 24 Tips of TYPO3 Fluid by Claus Due (Developer and Maintainer of TYPO3 Fluid).

My dear TYPO3 reader, As you know, my ritual ;) It’s time to say thanks to the TYPO3 people who contributed to the TYPO3 Fluid Open Source project. We appreciate your dedication and work on TYPO3 Fluid. Huge thanks to Claus Due, Let’s give big hands! #T3Kudos!

“TYPO3 Fluid - A fast, secure and extensible template engine for PHP.” - typo3.org

TYPO3 fluid is mainly used by the Front-end developers who integrate HTML/CSS/JavaScript to output at the website. While incorporating your templates in TYPO3, you don’t require knowledge of PHP scripting language - Just use innovative TYPO3 Fluid ;) Read more

Hmm, so you want to write some TYPO3 Fluid code that should be bypassed from the TYPO3 fluid cache. You can use the TYPO3 Fluid viewhelper call <f:cache.disable />.

<f:cache.disable>
   Write down your TYPO3 fluid code, which will consistently execute without the TYPO3 cache.
</f:cache.disable>

To create a variable, assign value and use it at your section or particular is helpful to write better TYPO3 fluid code. As a TYPO3 beginner, you may not know how to create TYPO3 fluid variables in many ways, as below.

<!-- Using TYPO3 Fluid ViewHelper -->
<f:variable name="fluidVar" value="Your Static Value"/>
<f:variable name="fluidVar">Assign Large Expression</f:variable>

<!-- Using TYPO3 Fluid Inline Notation -->
{f:variable(name: 'fluidVar', value: 'Your Static Value')}
{my:expensiveViewHelper() -> f:variable(name: 'fluidVar')}

Now it’s time to use our very own created variables in TYPO3 fluid. You can use it anywhere to render variables, pass to partial, verify with if conditions, etc. Here are a few snippets.

<!-- Create TYPO3 Fluid Variable -->
<f:variable name="fluidVar" value="Your Static Value"/>

<!-- Simply Print TYPO3 Fluid Variabe -->
<div class=”myClass”>{fluidVar}</div>

<!-- Pass as argument into TYPO3 Fluid f.render -->
<f:render partial="MyPartial" arguments="{fluidVar: fluidVar}"/>

You may be required to call values with a dynamic variable in some situations - I know it’s hard to understand what a dynamic variable is? But let’s have a look at a few TYPO3 fluid code examples to understand it well.

<!-- Example 1. Create Variable with Two-dimensional Array. And, let’s call the value of index-1 from fluidVar variable (using another variable call index) →

<f:variable name="fluidVar" value="{0: 'foo', 1: 'bar'}" />
<f:variable name="index" value="1" />

{fluidVar.{index}}
<!-- Output: bar -->

<!-- Example 2 -->
<f:variable name="fluidVarOne" value="Value of Variable 1" />
<f:variable name="fluidVarTwo" value="Value of Variable 2" />
<f:variable name="chooseType" value="Two" />

{fluidVar{chooseType}}
<!-- Output: Value of Variable 2 -->

Declares New Variable from Other Variable

In rare cases, you will need to alias from one variable to another. You can use <f:alias /> TYPO3 fluid viewhelper.

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

How to Add CSS/JavaScript In TYPO3 Fluid Template?

From TYPO3 v9, TYPO3 core provides a feature to add your JavaScript/CSS assets within your TYPO3 fluid template. Here is the snippet code.

<f:section name="HeaderAssets">
    <link rel="stylesheet" href="{f:uri.resource(path: 'Css/styles.css')}"/>
    <script type="text/javascript src="{f:uri.resource(path: 'JavaScript/script.js')}"></script>
</f:section>

<f:section name="FooterAssets">
    <link rel="stylesheet" href="{f:uri.resource(path: 'Css/styles.css')}"/>
    <script type="text/javascript src="{f:uri.resource(path: 'JavaScript/script.js')}"></script>
</f:section>

That’s quite simple; you can register and use multiple namespaces.

{namespace f=Vendor\MyFluidOverrides\ViewHelpers}
{namespace my=Vendor\MyExtensionOne\ViewHelpers}

For the TYPO3 extension developer, If you want to create the link to Add/Edit a particular table’s record, you can use <be:link /> ViewHelper.

<!-- Create New Record Link -->
<be:link.newRecord table="table_name" returnUrl="foo/bar" uid="-17"/>
<a href="/typo3/index.php?route=/record/edit&edit[table_name][-17]=new&returnUrl=foo/bar">
    Add record
</a>

<!-- Create Edit Record Link -->
<be:link.editRecord uid="42" table="table_name" returnUrl="foo/bar" />
<a href="/typo3/index.php?route=/record/edit&edit[table_name][42]=edit&returnUrl=foo/bar">
    Edit record
</a>

<!-- Create Simple Page Link -->
<f:be.link route="web_ts" parameters="{id: 92}">Go to web_ts</f:be.link>

At your TYPO3 custom backend module, Do you want to display a custom style information box? Just use <f:be.infobox /> ViewHelper.

<f:be.infobox title="Message title">your box content</f:be.infobox>

Use <f:inline /> TYPO3 Fluid ViewHelper.

<!-- Assign Variables from Your Controller -->
$view->assign('variable', 'value of my variable');
$view->assign('code', 'My variable: {variable}');

<!-- Render through TYPO3 Fluid Inline -->
{code -> f:inline()}

Do you want to create and assign default values? It will give assurance that your declared variable will always have some default values.

<!-- Giving variables default values if they are NULL -->
{class -> f:or(alternative: 'my-default') -> f:variable(name: 'class')}
{label -> f:or(alternative: 'No name') -> f:variable(name: 'label')}
{body -> f:or(alternative: 'Body not set') -> f:variable(name: 'body')}

<!-- Purpose: guarantee a value is filled for mandatory output -->
<div class="{class}">
  <h4>{label}</h4>
  <f:format.html>{body}</f:format.html>
</div>

In most cases, people always call static sections, which may create code redundancy. You should dynamically call your sections based on the value of your variables.

<!-- Using f:render to make "blocks" of output -->
Rendering into a variable and then using that variable can make the template more readable. This example is minimal; the bigger and more costly the rendering is, the more sense it makes to use this trick.

<f:section name="Icon">
  <span class="icon-{icon}"></span>
</f:section>

{f:render(section: 'Icon', arguments: {icon: 'twitter'}) -> f:variable(name: 'twitterIcon')}
{f:render(section: 'Icon', arguments: {icon: 'facebook'}) -> f:variable(name: 'facebookIcon')}

And use them as frequently as we want:

<div class="share">
  Share here!
  {twitterIcon -> f:format.raw()}
  {facebookIcon -> f:format.raw()}
</div>

<div class="also-share">
  Or here!
  {twitterIcon -> f:format.raw()}
  {facebookIcon -> f:format.raw()}
</div>

Do you want to perform simple mathematical operations within your TYPO3 fluid? Here it’s how;

<!-- Example 1. Simple math -->
<f:variable name="floatPercent" value="0.25" />
Percent done: {floatPercent * 100}%

<!-- Example 2. Manipulating Two Variables -->
<f:variable name="total" value="12" />
<f:variable name="done" value="3" />
Progress: {total - done} remaining.

<!-- Example 1. TypoScript Meets Fluid -->
<f:cObject typoscriptObjectPath="lib.math" data="20+22" />
lib.math = TEXT
lib.math {
  current = 1
  prioriCalc = 1
}

Maybe you don’t know, TYPO3 fluid provides to implement if..else...if nested conditions, Here is the example.

<!-- Else-if structure -->
Fluid can render "if" and "else" and we all know how that
works - but Fluid can also render "else-if" type structures:

<f:if condition="{var} > 100">
  <f:then> Overflow! </f:then>
  <f:else if="{var} > 90"> Danger! </f:else>
  <f:else if="{var} > 50"> Careful now. </f:else>
  <f:else> All good! </f:else>
</f:if>

In some situations, you may need to decide the based output of your used TYPO3 fluid viewhelpers. You can simply check within the If condition.

<f:if condition="<f:count subject='{post.comments}' /> > 0">
  <f:then>
    [...] Display comments here[...]
  </f:then>
  <f:else>
    No Comments found.
  </f:else>
</f:if>

Are you aware of <f:groupedFor /> TYPO3 Fluid ViewHelper? It’s interesting, consider below the practical code snippet.

<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>
<!-- Output: apple cherry strawberry banana -->

Here is the list available for loop iteration which helps you to manipulate your TYPO3 fluid code.

<!-- List of For loop iteration -->
itemIteration.index (0 based index of the iteration) 
itemIteration.cycle (the same as index, but starting from 1)
itemIteration.total (total number of items)
itemIteration.isFirst (TRUE for the first item in the iteration)
itemIteration.isLast (TRUE for the last item in the iteration)
itemIteration.isOdd (TRUE for odd cycles 1,3,5,...)
itemIteration.isEven (TRUE for even cycles 2,4,6,…)

<!-- How to use them -->
<ul> 
  <f:for each="{values}" as="value" iteration="iterator">
    <li class="{f:if(condition:'{iterator.isOdd}',then:'odd',else:'even')}">{value}</li> 
  </f:for>
</ul>

Just simply set {parsing off} to completely disable parsing of TYPO3 fluid code. It will ignore compiling your fluid code throughout the fluid scope.

<!-- Parsing enabled modifier -->
{parsing off}
The fluid code will not execute eg., {myFluidVar} <f:sections /> etc.

Using default parameters, you can define the default values of your particular TYPO3 fluid partial.

<!-- Default values when partial/section not found -->
<f:render partial="Missing" optional="1" default="Partial 1 not found" />

<f:render partial="AlsoMissing" optional="1">
  Partial 2 not found
</f:render>

<!-- Outputs: -->
Partial 1 not found
Partial 2 not found

That’s relatively easy! Using define and assign variables, you can call dynamic partial into your TYPO3 fluid code.

<f:section name="RenderAsText">
  Text version of object
</f:section>

<f:section name="RenderAsImage">
  Image version of object
</f:section

<!-- Prepare Variable to Call Partial -->
<f:variable name="myType" value="Text" />

<!-- Rendering section with a partially dynamic name -->
<f:render section="RenderAs{myType}" /> 

<!-- Rendering section with optional parameter as Default-value -->
<f:render section="RenderAs{myType}" optional="1" /> 

Using <f:spaceless /> TYPO3 Fluid ViewHelper, The white space within the code will be removed.

<!-- Removing meaningless whitespace -->
<f:spaceless>
  <div>
    <section>
      <p>
        Whitespace preserved inside tags
      </p>
      <p>But gets removed between tags</p>
    </section>
  </div>
</f:spaceless>

<!-- Outputs: -->
<div><section><p>
  Whitespace preserved inside tags
</p><p>But gets removed between tags</p></section></div>

With "contentAs" on f:render you can make it render the tag content and pass this to the partial as a variable you name. This enables you to use f:render and partials to wrap output in different ways. Consider the following example:

<f:render partial="MySpecialWrap" contentAs="content">
  <div class="wrappable-content">
    <h4>This content can be wrapped</h4>
    <!-- Fluid can be used without restrictions here -->
  </div>
</f:render>

<!--And the following template source in the "MySpecialWrap" partial template:-->

<!-- In partial MySpecialWrap.html -->
<div class="outerwrap wrap-foobar">
  <section>
    {content -> f:format.raw()}
  </section>
</div>

With the following PHP code, you can globally register TYPO3 Fluid Namespaces.

// Globally registered fluid namespace
$GLOBALS['TYPO3_CONF_VARS']['SYS']['fluid']['namespaces']['my'] =['MyVendor\\MyExtension\\ViewHelpers'];
// Makes "my" a namespace in Fluid, e.g. "<my:foobar>" resolves
// to class MyVendor\MyExtension\ViewHelpers\FoobarViewHelper 

$GLOBALS['TYPO3_CONF_VARS']['SYS']['fluid']['namespaces']['f'] = [
    'TYPO3Fluid\\Fluid\\ViewHelpers',
    'TYPO3\\CMS\\Fluid\\ViewHelpers'
];

Using <f:widget.autocomplete /> TYPO3 Fluid ViewHelper, you can quickly implement the auto-complete feature.

<!-- Create HTML Textbox -->
<input type="text" id="name" />

<!-- Initiate Autocomplete TYPO3 Fluid ViewHelper for create Textbox -->
<f:widget.autocomplete for="name" objects="{posts}" searchProperty="author">

<!-- Notes: You should add jQuery UI/UX library to use auto-complete feature -->
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8.4/jquery-ui.min.js"></script>
<link rel="stylesheet" href="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8.3/themes/base/jquery-ui.css" type="text/css" media="all" />
<link rel="stylesheet" href="http://static.jquery.com/ui/css/demo-docs-theme/ui.theme.css" type="text/css" media="all" />

I think you already know well about this, but still let me write for TYPO3 beginners ;)

<!-- Create TypoScript Object -->
lib.myObject = TEXT
lib.myObject.value = My TypoScript Object

<!-- Call TypoScript into Fluid -->
<f:cObject typoscriptObjectPath="lib.someLibObject" />

<!-- Output -->
My TypoScript Object

One another simple one, Please make sure never to use static labels or text within your TYPO3 code. Let’s keep using TYPO3’s excellent localization feature.

<!-- Add new Label/Text to XLIFF - /typo3conf/ext/yourextension/Resources/Private/Languages/locallang.xlf -->
<trans-unit id="myKey"> <source>My Text</source> </trans-unit>

<!-- Call Language-wise Text from XLIFF file -->
<f:translate key="myKey" />

As same as PHP’s printf, You can easily format your text using <f:format.printf /> TYPO3 Fluid ViewHelper.

<f:format.printf arguments="{number: 362525200}">%.3e</f:format.printf>
<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>
{someText -> f:format.printf(arguments: {1: 'TYPO3'})}

Any variables you render will not need to use f:format.raw even if they contain special HTML entities. Useful when you render formats other than HTML; or when you completely trust (read: escaped before assigning to view) all your variables that get output.

<!-- Disabling HTML escaping for an entire file -->
{escaping off}

Are you looking for your custom Renderable to manipulate stuff into your PHP?

<?php
use \TYPO3Fluid\Fluid\Core\Rendering\AbstractRenderable;
use \TYPO3Fluid\Fluid\Core\Rendering\RenderingContextInterface;

class MyRenderable extends AbstractRenderable
{
  public function render(RenderingContextInterface $renderingContext)
  {
    // Any PHP execution you want. The RenderingContext
    // will be the exact one that's active when you
    // render the renderable (and contains variables etc.)
    return 'My special rendering';
  }
}

<!-- then assign a view variable with an instance of MyRenderable -->
<f:render renderable="{renderable}" /> 

The "data" attribute on TagBasedViewHelpers. All ViewHelpers which use the AbstractTagBasedViewHelper parent class, or internally use the TagBuilder from Fluid, have the option of supporting arbitrary "data-*" attributes in two ways:

<!-- Prepare Data Attributes -->
Option 1. <v:h data-foobar="baz" data-biz="biz">content</v:h>
Option 2. <v:h data="{foobar: 'baz', biz: 'biz'}">content</v:h>

<!-- Output -->
Assuming "v:h" outputs a "div" tag, both examples output:
<div data-foobar="baz" data-biz="biz">content</div>

At complex websites, you may require to create dynamic layouts. Consider this example;

<!-- Declare layout -->
<f:variable name=”layout” value=”home” />

<!-- Dynamic call your layout -->
<f:layout name="Custom{layout}" />

Here is the list of hands TYPO3 fluid viewhelpers to format your text.

<!-- f:format.* -->
<f:format.date>{dateObject}</f:format.date>
<!-- Output: 1980-12-13 -->

<!-- f:format.case -->
<f:format.case>Some Text with miXed case</f:format.case>
<!-- Output: SOME TEXT WITH MIXED CASE -->

<!-- f:format.nl2br -->
<f:format.nl2br>{text_with_linebreaks}</f:format.nl2br>
<!-- Output: Text with line breaks replaced by <br /> -->

<!-- f:format.stripTags -->
<f:format.stripTags>Some Text with <b>Tags</b></f:format.stripTags>
<!-- Output: Some Text with Tags -->

Whenever you have too many conditions, try to avoid <f:if /> and Try to use <f:switch /> TYPO3 ViewHelper.

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

Claus Due (aka @NamelessCoder) developed and maintained the following two TYPO3 fluid repositories.

(CLI) TYPO3 Fluid Template Precompiler

The command-line tool scans your TYPO3 site for and compiles it without rendering Fluid template files. Simply put, it warms up the Fluid template cache by parsing and compiling all templates without rendering them.

composer require namelesscoder/typo3-cms-fluid-precompiler
./vendor/bin/fluid-precompile
./vendor/bin/fluid-precompile --extension my_extension

(TYPO3 Extension) TYPO3 Fluid Template Precompiler

Provides a backend module and cache menu item to compile Fluid templates detected on the system without rendering the output. The backend module, in addition, provides very detailed information about the efficiency of individual template files.

In Fluid, when you nest ViewHelper expressions, you are required to escape any nested quotes. This can quickly become difficult:

<!-- Bad Example -->
<f:render partial="Foobar" arguments="{
  label: '{f:if(condition: lll, then:
  \'{f:translate(key: \\'mylabel\\')}\',
  else: \'foobar\')}
}" />

<!-- Good Example -->
{f:translate(key: 'mylabel')
  -> f:if(condition: lll, else: 'foobar')
  -> f:variable(name: 'label')}
<f:render partial="Foobar" arguments="{label: label}" />

Package which hooks into the Pattern Lab Fluid Edition to write your patterns as proper TYPO3 CMS Fluid template files into an extension folder - which then is more or less plug and play.

This TYPO3 extension puts frontend developers in a position to create encapsulated components in pure Fluid. By defining a clear interface (API) for the integration, frontend developers can implement components independent of backend developers. The goal is to create highly reusable presentational components with no side effects and aren't responsible for data acquisition.

This extension provides you with a complete set of ViewHelpers for dealing with FPDF by using Fluid. You can use the ViewHelpers easily in your own Extensions just by defining the fpdf-Namespace. Additionally, you can use the built-in plugin for displaying predefined PDF. This plugin offers you automatically all available PDFs.

VS Code - TYPO3 Fluid Snippets

A collection of snippets for the TYPO3 Fluid syntax.

VS Code - TYPO3 Code Snippets

TYPO3 Code Snippet integration. Just type the letters 't3' to get a list of all available TYPO3 Code Snippets.

VS Code - TYPO3 VHS Snippets

A collection of snippets for the TYPO3 VHS: Fluid ViewHelpers

VS Code - flux-snippets

Snippets for TYPO3 Flux ViewHelpers

Atom - TYPO3 Fluid Language package

Adds syntax highlighting to TYPO3 Fluid tags and inline notations in Atom.

Last but not least, although we have a powerful TYPO3 Fluid template engine, TYPO3 does not have a common TYPO3 template method. Of course, we have too much flexibility, and everyone has their own approach to create a TYPO3 template ;) I recommend reading the below article.

• [Wanted] Official TYPO3 Templates Builder Since 20 Years!
• Best Practice for TYPO3 Template Integration

Thanks for reading this long TYPO3 article. I hope you dig in-depth into TYPO3 fluid.

Do you know any tips and tricks for TYPO3 fluid? What’s your favorite tip from the above list? Do you have any questions or need help with TYPO3 fluid? I would love to receive your message in the comment box.

Have a Happy TYPO3 Fluiding!