How to Use TYPO3 Fluid? (Basic to Advanced Guide)

Published on :  
Sanjay Chauhan
Development

TYPO3 Fluid - A fast & secure template engine of TYPO3 CMS. No matter, if you are a TYPO3 developer or TYPO3 integrator; You must have expertise in TYPO3 fluid. Are you looking for essential advanced level TYPO3 Fluid skills? You landed at the right place; here we go!

How to Use TYPO3 Fluid? (Basic to Advanced Guide)

TYPO3 Fluid - A fast & secure template engine of TYPO3 CMS. No matter, if you are a TYPO3 developer or TYPO3 integrator; You must have expertise in TYPO3 fluid. Are you looking for essential advanced level TYPO3 Fluid skills? You landed at the right place; here we go!

TYPO3 Fluid is helpful for creating TYPO3 templates or for custom extension development. It’s the heart of TYPO3 to render UI/UX. This article will learn what/why fluid, history of fluid, basic architecture, useful viewhelpers, custom viewhelper, best practices, tips & tricks of TYPO3 Fluid.

Namaste, my dear TYPO3 reader, As you know, my ritual ;) Before we start - Let’s remember the TYPO3 people who contributed to the TYPO3 Fluid Open Source project. I appreciate their time and efforts - Let’s give big hands #T3Kudos!

Guide to TYPO3 Fluid

What's TYPO3 Fluid?

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

It means TYPO3 fluid is mainly used by the Frontend 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 ;)

Why TYPO3 Fluid?

Why does the TYPO3 community create a fluid template engine?

  • Security: TYPO3 always focuses on security; Fluids protect against usual security threats like XSS.
  • Extendibility: TYPO3 Fluid is very flexible to use and extend unlimited ways.
  • Easy to Use: Whole TYPO3 Fluid has been designed with simple XML, so it’s very comfortable to use in HTML templates; you don’t require any special syntax ;)

Your First Impression to TYPO3 Fluid Code

Take a quick look at the sample code of TYPO3 fluid code, and I’m sure it’s pretty easy to read and understand.

 

<!-- Fluid Template Sample Code -->
<h4>How easy to learn TYPO3 Fluid Template?</h4>
<p>
    <f:if condition="{myExpression}">
     <f:then>Indeed, It’s very easy!</f:then>
     <f:else>Hmm, Seems bit difficult</f:else>
    </f:if>
</p>

<!-- Output of TYPO3 Fluid In Browser -->
<h4>How easy to learn TYPO3 Fluid Template?</h4>
<p>Indeed, It’s very easy</p>

 

History of TYPO3 Fluid

TYPO3 Fluid’s history is slightly different; it was initiated in 2008 for TYPO3 Extbase and TYPO3 Phoenix (aka Neos CMS). And, the TYPO3 community decided to use the TYPO3 Fluid template engine in the TYPO3 core too.

Mr. TYPO3 Fluid Man - Claus Due refactored the codebase in a standalone package; It was then used as a library since TYPO3 v8 and Neos/Flow Framework.

Installation of TYPO3 Fluid

Installation of TYPO3 Fluid

EXT.fluid is part of the TYPO3 core system extension; you don’t need to perform any extra steps to install and configure.

Sometimes your TYPO3 administrator may miss to consider EXT.fluid_styled_content extension in composer-based TYPO3 installation. You can install it as below.

 

composer require typo3/cms-fluid-styled-content

 

Support & Help on TYPO3 Fluid

Are you facing any problems with TYPO3 fluid? You can find further development found at https://github.com/TYPO3/Fluid. You can also submit tickets or questions at Github.

Who Needs TYPO3 Fluid?

TYPO3 itself requires the Fluid template engine because the whole TYPO3 backend has been rendered with TYPO3 Fluid. As this engine does not know anything about TYPO3, the engine is extended by TYPO3 within the system extension ext:fluid.

Apart from that, Frontend developers who are developing frontend templates with HTML, CSS, JS will need to learn TYPO3 fluid. You can easily integrate your TYPO3 template using TYPO3 Fluid.

Basics of TYPO3 Fluid

Let’s begin learning TYPO3 fluid from basics like the structure of files, syntax, etc.

File Structure of TYPO3 Fluid

Take a look at the below folders and file structure, “Layouts, Partials, Templates” main design of TYPO3 Fluid. We will learn in-depth in the following sections.

 

typo3conf/ext/xtension_key

└── Resources
    ├── Private
    │   ├── Languages
    │   ├── Layouts
    │   │   └── Layout1.html
    │   ├── Partials
    │   │   └── MyPartial.html
    │   └── Templates
    │       └── Template1.html
    └── Public
        ├── CSS
        ├── Images
        └── JavaScript

 

Syntax of TYPO3 Fluid

TYPO3 Fluid has two main syntax formats 1. Tags mode, 2. Inline Notation. Mostly you will need to use tags-mode, e.g., <f:format.html />, But you will need to display something in the tag’s attribute, then you can use Inline notation, e.g., class=”my-class-{variable}”.

Tag vs Inline Mode

 

<!-- Example of Tag TYPO3 Fluid Code -->
<f:count>{arrVariable}</f:count>

<!-- Example of In-line Notation TYPO3 Fluid Code -->
{arrVariable -> f:count()}

<!-- Bad Example - When In-line Notation -->
<ol class="item-count-<f:count>{arrVariable}</f:count>">
  My List
</ol>

<!-- Good Example - When In-line Notation -->
<ol class="item-count-{arrVariable -> f:count()}">
  My List
</ol>

 

TYPO3 Fluid Expression

In Inline-notation, Expression “{}” is one of the hearts of TYPO3 fluid, where you can render anything as well as set conditions.

 

{variable}
{myArray -> f:count()}
{myPossiblyArray as array}
{checkVariable ? thenVariable : elseVariable}
{myNumber + 3}

The Architecture of TYPO3 Fluid

TYPO3 fluid has central three pillars,

  • Templates are the individual files you either render directly or resolve using a controller name and action.
  • Layouts that are optional, shared files that are used by Templates and which render sections from Templates.
  • Partials are the shared files that can be rendered from anywhere inside Fluid and contain reusable design bits.

1. Prepare Templates

 

<!-- File: /typo3conf/ext/extension_key/Resources/Private/Templates/MyTemplate.html -->

<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
data-namespace-typo3-fluid="true">

<!-- Define section block call “MyTemplate” -->

<f:section name="MyTemplate">
The main template’s section will render.
</f:section>

<!-- Let’s Call “Main” section for testing -->
<f:render section="MyTemplate" />
</html>

 

2. Prepare Layouts & Call Templates

 

<!-- File: /typo3conf/ext/extension_key/Resources/Private/Layouts/MyLayout.html -->
<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers" data-namespace-typo3-fluid="true">

<!-- Define Layout -->
<f:layout name="MyLayout" />

<!-- Let’s Call “Main” from Templates -->
<f:render section="MyTemplate" />
</html>

 

3. Prepare Partials & Call at Templates

Partials are the smallest part of the TYPO3 fluid; you can call partials anywhere into Templates, Layouts, and or-even into other Partials.

Prepare Partial

 

<!-- File: /typo3conf/ext/extension_key/Resources/Private/Partials/MyPartial.html -->

<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers" data-namespace-typo3-fluid="true">
<p>My First Partial: {variable}</p>
</html>

 

Let’s Call-In Template

 

<!-- File: /typo3conf/ext/extension_key/Resources/Private/Templates/MyTemplate.html -->

<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers" data-namespace-typo3-fluid="true">

<!-- Define section block call “MyTemplate” -->
<f:section name="MyTemplate">

<!-- Call Partials here… ->
<f:render partial="MyPartial" arguments="{variable: ‘my-value’}" />
</f:section>

<!-- Let’s Call “Main” section for testing -->
<f:render section="MyTemplate" />
</html>

TYPO3 Fluid ViewHelpers

ViewHelpers are built-in special partials available within TYPO3 Fluid. Fortunately, the TYPO3 community already created many ViewHelpers, which can save our time by avoiding writing custom Partials ;)

Useful Fluid ViewHelpers

Here, I want to let you know the most valuable and crucial TYPO3 Fluid ViewHelpers, which can be used in your daily life TYPO3 fluid templates.

 

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

<!-- f:link.* -->
<f:link.typolink parameter="{link}">
   Linktext
</f:link.typolink>
<!-- Output: <a href="/page/path/name.html?X=y" title="testtitle with whitespace" target="_blank">
   Linktext
</a> -->

<!-- f:widget.* -->
<f:widget.paginate objects="{blogs}" as="paginatedBlogs">
   use {paginatedBlogs} as you used {blogs} before, most certainly inside
   a <f:for> loop.
</f:widget.paginate>

<!-- f:debug -->
<f:debug>{testVariables.array}</f:debug>
<!-- Output: Debug screen -->

<!-- f:cObject -->
<f:cObject typoscriptObjectPath="lib.customHeader" data="{article}" currentValueKey="title" />
<!-- Output: Display from your defined TypoScript object
lib.customHeader = COA
lib.customHeader {
    10 = TEXT
    10.field = author
    20 = TEXT
    20.current = 1
}
 -->

<!-- f:image -->
<f:image src="EXT:myext/Resources/Public/typo3_logo.png" alt="alt text" />

<!-- Output: <img alt="alt text" src="/blog/typo3conf/ext/myext/Resources/Public/typo3_logo.png" width="396" height="375" /> -->
<f:image image="{imageObject}" />
<!-- Output: <img alt="alt set in image record" src="fileadmin/_processed_/323223424.png" width="396" height="375" /> -->

Inline Notation
{f:image(src: 'EXT:viewhelpertest/Resources/Public/typo3_logo.png', alt: 'alt text', minWidth: 30, maxWidth: 40)}

<!-- f:media -->
<f:media file="{file}" width="400" height="375" />

<!-- Output: <img alt="alt set in image record" src="fileadmin/_processed_/323223424.png" width="396" height="375" /> -->
<f:media file="{file}" width="400" height="375" />
<!-- Output: <video width="400" height="375" controls><source src="fileadmin/user_upload/my-video.mp4" type="video/mp4"></video> -->


<!-- f:translate -->
<f:translate key="key1" />

<f:translate key="LLL:EXT:myext/Resources/Private/Language/locallang.xlf:key1" />
{f:translate(key: 'someKey', arguments: {0: 'dog', 1: 'fox'}, default: 'default value')}

<!-- Your XLFF File -->
<trans-unit id="someKey" resname="someKey">
    <source>Some text about a %s and a %s.</source>
</trans-unit>

<!-- f:form.* -->
<f:form action="..." name="customer" object="{customer}">
    <f:form.hidden property="id" />
    <f:form.textfield name="myTextBox" value="default value" />
    <input type="text" name="myTextBox" value="default value" />
</f:form>

<!-- f:comment -->
<f:comment>Some coment</f:comment>

Variables, Conditions, Loops in TYPO3 Fluid

TYPO3 Fluid smartly provides features to define variables, conditions, and loops to display data in a customizable way.

TYPO3 Fluid Variables

 

{f:variable(name: ‘FluidVariable’, value: ‘Assign Value’)}
<f:variable name=”FluidVariable”>Assign Value</f:variable>

 

TYPO3 Fluid If Condition

 

<f:if condition="{FluidVariable} > 100">
    <f:then>True</f:then>
    <f:else>False</f:else>
</f:if>

 

TYPO3 Fluid Foreach Loop

 

<f:variable name=”FluidArray”>{fruit1: ‘apple’, fruit2: ‘pear’, fruit3: ‘banana’, fruit4: ‘cherry’}</f:variable>
<f:for each=”{FluidArray}” as=”fruit” key=”label”>
<li>{label}: {fruit}</li>
</f:for>

 

TYPO3 Fluid Switch Case Condition

 

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

Explore More

How To Create Custom TYPO3 Fluid ViewHelper?

As mentioned at the beginning, TYPO3 fluid provided unlimited extendibility. Suppose you want to create your own ViewHelper which can manipulate and display end-result. TYPO3 fluid allows to create custom TYPO3 viewhelper by writing a few PHP scripts and renders. Here is the simple example of TYPO3 fluid viewhelper.

Step 1. Create Custom View Helper’s PHP Class

 

<?php
// File: /typo3conf/ext/extension_key/Classes/ViewHelpers/MystyleViewHelper.php

namespace Vendor\Package\ViewHelpers;

class MystyleViewHelper extends \TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper
{
    /**
     * initialize
     *
     */
    public function initializeArguments()
    {
        $this->registerArgument('text', 'string', 'My custom argument', true);
    }
    /**
     * render inline text
     * @param array $attributes attributes to add
     * @return string content
     */
    public function render()
    {
        $content = '<div class="my-custom-style">'.$this->arguments['text'].'</div>';
        return $content;
    }
}
?>

Step 2. Use Your ViewHelper at Templates/Partials/Layouts

 

<!-- File: /typo3conf/ext/extension_key/Resources/Private/Templates/YourTemplate.html-->

{namespace ns=Vendor\Package\ViewHelpers}

<!-- Tag Based ViewHelper -->
<ns.mystyle text="Special content" />

<!-- Inline Notation ViewHelper -->
{ns:mystyle(text:'Special content')}

Tips & Tricks of TYPO3 Fluid

That’s it to learn the basics to advanced level knowledge of TYPO3 Fluid. But still, I want to share a few excellent tips and tricks to explore more about TYPO3 fluid.

Reference of EXT.fluid_styled_content

While you are learning the structure and syntax of TYPO3 fluid, it’s always good to explore TYPO3 core’s system extension EXT.fluid_styled_content.

TYPO3 Fluid Code Documentation

Fluid Powered TYPO3

Fluid Powered TYPO3 is a family of TYPO3 extensions designed to boost productivity and flexibility when creating CMS templates.
- FluidTYPO3.org

Official Website Documentation

Meet Fluid + Atom Design

Fluid Components for TYPO3 enables frontend developers to implement consistent web designs with reusable components. Fluid Style Guide provides a dedicated frontend workshop as well as a powerful collaboration tool for all project stakeholders.

Official Website Documentation

IDEs Support TYPO3 Fluid

TYPO3 Fluid FOSS Support

This plugin is in an early draft stage. The project aims to provide a fully OpenSource plugin for the Fluid Template Language.

Get PHP Storm Fluid Get Premium PHP Storm Fluid

VS Code TYPO3 Fluid Snippets

A collection of snippets for the TYPO3 Fluid syntax.

Get TYPO3 Fluid Snippets

TYPO3 Code Snippets

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

Get TYPO3 Code Snippets

TYPO3 VHS Snippets

A collection of snippets for the TYPO3 VHS: Fluid ViewHelpers

Get TYPO3 VHS

flux-snippets

Snippets for TYPO3 Flux ViewHelpers

Get TYPO3 Fluid VHS

TYPO3 Books

You can learn TYPO3 Fluid from available TYPO3 Extbase and Fluid Books. Explore Best TYPO3 Books.

24 Fluid Tips

In December of 2017, Claus Due (Developer and Maintainer of TYPO3 Fluid) shared 24 valuable Tips and Tricks. This Post republishes all of them for future reference. Take a look at 24 Fluid Tips.

Fluid Tags Convert to Inline Notation

To save your time, there is an online tool to convert your Fluid tags to inline notation. Explore http://www.fluid-converter.com/ 

Common TYPO3 Fluid Templates Method

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.

Closure!

Thanks for reading my article; I hope you like and explore fundamental to advanced level TYPO3 fluid skill.

No matter, If you want to become a TYPO3 integrator or developer, you should have expertise in the TYPO3 fluid template engine. Do you have any questions, or facing any TYPO3 Fluid issues? Or, Do you know any better resources to learn TYPO3 Fluid? Feel free to write to the comment box, and I’ll be happy to help you.

Have a Happy Templating With Awesome TYPO3 Fluid!

Your One Stop Solutions for Custom TYPO3 Development

  • A Decade of TYPO3 Industry Experience
  • 250+ Successful TYPO3 Projects
  • 87% Repeat TYPO3 Customers
Get Your Free Quote
Sanjay Chauhan

Sanjay Chauhan

CTO at T3Planet & NITSAN

Sanjay Chauhan, Co-Founder of NITSAN (Award winning TYPO3 agency) and Pioneer of T3Planet (first-ever TYPO3 Store).

A true TYPO3 fanatic since 2010. I bring strong TYPO3 experience in building customer-business…

More From Author

Previous Article
TYPO3 Database Access Options [Substitute of EXT.phpMyAdmin]
Next Article
Guide to TYPO3 Translation & Localization (With Useful Extensions)

Post a Comment

×
Captcha Code Can't read the image? Click here to refresh
  • user
    Andreas Drechsler 2023-07-14 at 3:19 pm
    I've always been intrigued by TYPO3 Fluid, but never knew where to start. Your blog post served as the perfect introduction, taking me from the basics to more advanced techniques. I appreciate how you made the learning process enjoyable and accessible. Great job!
  • user
    Ralf Wechsler 2021-04-13 at 7:14 am
    Very vast and deep information about TYPO3 Fluid.
  • user
    Lucas Muench 2021-04-13 at 7:12 am
    Great work Sanjay! I have always waited for this kind of article on TYPO3 Fluid. This guide helps to learn about Fluid templates from basic to advanced level.

You May Also Like

Translating pages in TYPO3

How to Translate Pages & Content in TYPO3 CMS?

Dhyana Chauhan
Development
What PHP Versions Does TYPO3 Support?

What PHP Versions Does TYPO3 Support?

Sanjay Chauhan
Development
YPO3 Content Elements: Flexform vs. TCA

TYPO3 Content Elements: Flexform vs. TCA

Sanjay Chauhan
Development