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

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!

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

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

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.

Fluid Powered TYPO3

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

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.

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.

VS Code TYPO3 Fluid Snippets

A collection of snippets for the TYPO3 Fluid syntax.

TYPO3 Code Snippets

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

TYPO3 VHS Snippets

A collection of snippets for the TYPO3 VHS: Fluid ViewHelpers

flux-snippets

Snippets for TYPO3 Flux ViewHelpers

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!

Post Comment

Your email address will not be published. Required fields are marked *

×

Name is required!

Enter valid name

Valid email is required!

Enter valid email address

Comment is required!

Google Captcha Is Required!

Comments :

  • Ralf Wechsler April 13, 2021 At 7:14 am
    Very vast and deep information about TYPO3 Fluid.
  • Lucas Muench April 13, 2021 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.

How to Install/Update TYPO3 & Extension via TYPO3 Composer

Are you new to the TYPO3 Composer world? And, Are you looking for quick steps to install, update and remove TYPO3 composer…

Easy TypoScript Tutorial - Beginner's Guide (2020)

Myth: TypoScript Is a Scripting Language

Welcome TYPO3 Beginners, In this article, you will find everything on what/why/how TypoScript. My ultimate goal is to step-by-step…

How to Build a TYPO3 website in minutes with TYPO3 SaaS?

How to Build a TYPO3 website in minutes with TYPO3 SaaS?

Introducing TYPO3 SaaS to build a fast, User-friendly SaaS website without worrying about coding, design, and hosting. Everything…

Stay up to date with our recent TYPO3 Blogs, news, & updates