Study guide · Fluid ViewHelpers
ViewHelpers at work: text, images, links and head data
With Fluid alone, data sits in the template in its raw form. ViewHelpers turn it into a readable date, a properly scaled photo, a link or a meta tag. On this page you help Mara extend the website of a music school. Along the way you get to know the most important ViewHelpers for text, dates, images, crops, links, head data and assets. Afterwards you know which ViewHelper is meant for what, and where its traps are.
The example: Lindenau Music School
Mara is an integrator. She builds the website of Lindenau Music School. Everything lives in her site package lindenau_site, the Composer package lindenau/site, in a Composer project with TYPO3 14.3. The website has course pages for instruments, a page with the teachers and a concert calendar. The teachers' photos should look sharp and load fast. Every course page and every concert should have its own meta tags.
A ViewHelper is a Fluid tag with logic behind it. The namespace f is predefined everywhere, so you do not need to import it. You can call most ViewHelpers in two ways: as a tag, or inline in curly braces. Inline, you can pass a value on to the ViewHelper with an arrow.
<f:format.crop maxCharacters="40">{course.title}</f:format.crop>
{course.title -> f:format.crop(maxCharacters: 40)}The basics of variables, escaping and conditions are covered in the course “Fluid-Grundlagen”. This page is about the ViewHelpers themselves.
Formatting text
The format group holds many small helpers. For the course descriptions, Mara mainly needs these:
- The ViewHelper
f:format.cropcuts a text to the number of characters in maxCharacters. If it cut something, it appends an ellipsis by default. It does not cut in the middle of a word. - The ViewHelper
f:format.nl2brturns every line break into an HTML line break. This suits multi-line text fields without an editor. - The ViewHelper
f:format.currencyoutputs a number as an amount of money, with a decimal separator and a thousands separator. You set the currency sign with currencySign. That way the course fee appears as 45,00 €. - The ViewHelper
f:format.numberformats numbers without a currency. - The ViewHelper
f:format.bytesshows file sizes in a readable way, for example for the registration form download. - The ViewHelper
f:format.trimremoves spaces at the edges. The ViewHelperf:format.paddingpads a text to a length. The ViewHelperf:format.casechanges upper and lower case.
Rich text: You output text from the rich text editor with the ViewHelper f:format.html. It sends the text through a parseFunc, by default through lib.parseFunc_RTE. This turns internal TYPO3 links that start with t3 into real URLs and cleans up the HTML.
Be careful with two ViewHelpers: Fluid normally escapes variables. The ViewHelper f:format.raw switches this escaping off. The ViewHelper f:format.htmlentitiesDecode turns escaped characters back into real HTML. Both can lead to cross-site scripting if visitor input passes through them. The ViewHelpers f:format.htmlspecialchars and f:format.stripTags, on the other hand, make the output safer. The first escapes, the second removes tags.
Date and time
Mara outputs the concert dates with the ViewHelper f:format.date. It accepts an object with DateTimeInterface or a text that PHP understands as a date. That can be a timestamp or a relative value such as “plus one week”.
Two ways to set the format:
- The argument format takes the PHP date characters. The letter d stands for the day, m for the month and capital Y for the four-digit year. With dots in between, that gives 31.12.2026.
- The argument pattern takes the ICU notation, such as two small d, a dot, four capital M, a space and four small y. Together with the argument locale, for example de-DE, you get translated month names such as “31. Dezember 2026”.
<f:format.date format="d.m.Y">{concert.date}</f:format.date>
<f:format.date pattern="dd. MMMM yyyy" locale="de-DE">{concert.date}</f:format.date>
<f:format.date pattern="FULLDATE" locale="de-DE">{concert.date}</f:format.date>
<f:format.date format="d.m.Y" base="{concert.date}">+1 week</f:format.date>
<f:format.date format="H:i" timezone="Europe/Berlin">{concert.date}</f:format.date>The key rules:
- If format and pattern are both set, pattern takes precedence. The description of the argument says so.
- If neither is set, the ViewHelper takes the setting ddmmyy under SYS in the global TYPO3 configuration. The default is Y-m-d, for example 2026-12-31.
- The argument locale only works together with pattern. With format you get the PHP characters without translation.
- For a fully localized date without your own pattern, pattern knows the presets FULL, LONG, MEDIUM and SHORT. There are also variants such as FULLDATE for the date only and FULLTIME for the time only. FULLDATE with de-DE gives, for example, “Donnerstag, 31. Dezember 2026”.
- The argument timezone converts the date into a time zone before output. A concert stored in UTC appears in Berlin time with Europe Berlin.
- The argument base is the reference point for relative values such as plus one week or minus one year. Without base, the current time applies.
Text fields with f:render.text
Since TYPO3 14.2 there is the ViewHelper f:render.text for text fields of records. It reads the TCA configuration of the field and picks the right output by itself. That way it replaces three earlier approaches:
- For a simple input field it replaces outputting the variable directly. The text is escaped.
- For a multi-line text field it replaces the ViewHelper
f:format.nl2br. Line breaks become HTML line breaks. - For a rich text field it replaces the ViewHelper
f:format.html.
Translations from XLIFF files and images are not text fields. They keep their own ViewHelpers.
The argument field is required. It names the database field. You pass the record with the argument record or as the content of the ViewHelper.
{record -> f:render.text(field: 'header')}
<f:render.text record="{record}" field="bodytext" />
<f:render.text record="{teacher}" field="sub_title" optional="true" />Requirement in the content element: For the variable record in the template to be a record object with TCA information, the content element needs the data processor record-transformation. Without it there is only raw data, and the ViewHelper cannot classify the field.
The ViewHelper can also handle Extbase models. But it expects the field name from the database, not the property name. If the teacher model has the property subTitle from the field sub_title, you write sub_title. If the field is missing, you get an error. With optional set to true, you get null instead. This also applies to record objects. The model must also map every field you output, and the type field too if the TCA has one.
Images with f:image
The ViewHelper f:image resizes, crops or converts an image if needed. In the end it outputs a finished img tag. If you only need the URL of the processed image, you use the ViewHelper f:uri.image.
There are two ways to pass the image:
- The argument image expects an object from the file abstraction layer FAL, that is a File or a FileReference. This is how the teachers' photos get into the template.
- The argument src takes a path with
EXT:, a combined FAL identifier or a UID. This is how Mara includes the logo from the site package.
The ViewHelper does not process external URLs. An image from another address is neither downloaded nor scaled.
<f:image image="{teacher.photo}" width="800c" cropVariant="default" loading="lazy" alt="{teacher.name}" />
<f:image src="EXT:lindenau_site/Resources/Public/Images/logo.png" width="200" fileExtension="webp" />
<f:image src="EXT:lindenau_site/Resources/Public/Images/logo.png" width="200" base64="true" />The important arguments:
- For width and height you give pixels. The suffix c crops. A width of 800c gives an image cropped to exactly 800 pixels wide. With the suffix m, the value is an upper limit. The image is scaled proportionally and gets no larger than that.
- With cropVariant you choose a stored crop, for example mobile. The default is default.
- Setting crop to false removes the stored crop. Then the whole image is used.
- fileExtension sets the target format, for example webp. The image is converted if needed. This works no matter whether you use image or src.
- Setting base64 to true writes the image data as a data URI directly into the src attribute. This is meant for HTML emails, for example in FluidEmail templates.
- The tag-based ViewHelper simply copies other attributes, such as loading with the value lazy, or alt, into the img tag.
Default target formats: The setting imageFileConversionFormats under GFX in the global TYPO3 configuration controls which format is produced on conversion. Web formats such as jpg, png, gif, svg and webp are kept by default. Everything else becomes png. If the setting consists only of the key default with the value webp, TYPO3 converts everything to WebP. If the entries for jpg and png stay in place, those formats are still passed through.
Responsive images with f:image.srcset
The teachers' photos should be small on a phone and sharp on a large screen. For that, the img or source tag needs a srcset attribute with several image sizes. In the past you wrote many calls of f:uri.image by hand. Since TYPO3 14.2 there is the ViewHelper f:image.srcset.
From a single setting it creates all image variants and returns the finished list of URLs and descriptors. There are two kinds of descriptors:
- Widths such as 400w and 800w refer to the width of the image file.
- Pixel densities such as 1x and 2x refer to the pixel density of the screen.
You must not mix the two kinds. TYPO3 stops with an error if you do. For pixel densities, TYPO3 needs a base width for 1x, from which it calculates 2x and 3x. You set it with referenceWidth. For width descriptors, referenceWidth has no meaning.
You still steer which image the browser finally picks with the HTML attributes sizes and media. The ViewHelper does not make them unnecessary.
Picture with crops: On the desktop the photo should be wide, on a phone square. For that, each source element in the picture element gets its screen range through media and its own crop through cropVariant. The img inside is the fallback for old browsers.
<picture>
<source media="(min-width: 1000px)" sizes="100vw"
srcset="{f:image.srcset(image: teacher.photo, srcset: '1000w, 1400w', cropVariant: 'desktop')}" />
<source
srcset="{f:image.srcset(image: teacher.photo, srcset: '1x, 2x', referenceWidth: 400, cropVariant: 'mobile')}" />
<f:image image="{teacher.photo}" width="400" cropVariant="mobile" alt="{teacher.name}" />
</picture>Crops with crop variants
Crop variants are several stored crops of the same image, each with its own aspect ratio. The music school's editors crop a photo in the backend once wide for desktop and once square for mobile. In the template you choose the variant with cropVariant.
Where are they defined? The variants live in the TCA of the field crop in the table sys_file_reference. The field has the type imageManipulation. Alternatively you set them with TCEFORM in page TSconfig. For each variant you define a title, the allowed aspect ratios with allowedAspectRatios, and three areas:
- The cropArea is the initial crop.
- The focusArea marks the important part of the image, for example the face. It helps with responsive crops.
- The coverAreas show areas that will be covered later, for example by text on top of the image.
You give all areas in relative values between 0 and 1.
$GLOBALS['TCA']['tt_content']['types']['textpic']['columnsOverrides']['image']['config']['overrideChildTca']['columns']['crop']['config']['cropVariants'] = [
'mobile' => [
'title' => 'Mobil',
'allowedAspectRatios' => ['1:1' => ['title' => '1:1', 'value' => 1.0]],
],
'default' => ['disabled' => true],
];Only for one content type: With overrideChildTca on the field image of tt_content, a change applies to all content types. If only the type textpic should get an extra variant, you put overrideChildTca into the columnsOverrides of that type.
Switching variants off: overrideChildTca is merged with the TCA of sys_file_reference. So simply leaving out a key does not remove a variant. That is what the keyword disabled is for. If you set it to true for the variant default, it disappears for that field.
Cropping all at once: Since TYPO3 14.2 the image editor shows a checkbox that lets editors crop all variants at the same time. It only appears if the variants are configured identically apart from the title, that is with the same aspect ratios. You exclude a different variant, for example one for a list view, with excludeFromSync.
Links and URLs
There are two families for links. The ViewHelpers in the link group create the whole a tag. The ViewHelpers in the uri group only return the address, for example for an attribute. So the ViewHelper f:uri.page only outputs the URL, while the ViewHelper f:link.page outputs a finished link.
- The ViewHelper
f:link.pagelinks to a page in the page tree through pageUid. With additionalParams you add parameters. With language you link to another language. Setting absolute to true creates a full URL with the domain. - The ViewHelper
f:link.typolinkpasses the argument parameter to typolink. That way it understands the values from link fields: internal links starting with t3, and short forms such as “12 _blank” with target, class and title. The ViewHelperf:uri.typolinkreturns only the URL for it. - The ViewHelper
f:link.emailcreates a mailto link. It knows the arguments email, cc, bcc, subject for the subject line and body. The argument title only sets the title attribute of the link. - The ViewHelper
f:link.externalis for other websites, the ViewHelperf:link.filefor files, and the ViewHelperf:link.actionfor Extbase actions.
<f:link.page pageUid="12" language="1" absolute="true">Piano course</f:link.page>
<f:link.typolink parameter="{record.link}">Learn more</f:link.typolink>
<f:link.email email="office@example.org" subject="Anmeldung">Write to us</f:link.email>
<f:link.page pageUid="12" addQueryString="untrusted">Keep filters</f:link.page>Spam protection: The ViewHelper f:link.email does not protect addresses on its own. It follows the TypoScript setting spamProtectEmailAddresses.
Keeping current parameters: If addQueryString is set, the current query parameters stay in the link. With the value untrusted, all parameters are added explicitly, including untrusted ones. According to the description, this can cause problems with cached links.
Head area and meta tags
Since TYPO3 14.0 there are two ViewHelpers that write any markup into the page. Both use the PageRenderer API internally.
- The ViewHelper
f:page.headerDataadds its content to the head of the page, for example preload, preconnect or dns-prefetch links. - The ViewHelper
f:page.footerDatawrites its content right before the closing body tag, for example a tracking script.
For stylesheets and scripts you are better off with the asset ViewHelpers from the next section. They use an identifier and prevent duplicates. The head data ViewHelpers are meant for other markup and have no identifier.
Meta tags from Fluid: Also since TYPO3 14.0, the ViewHelper f:page.meta sets meta tags right in the template. It uses the MetaTagManager, just like TypoScript and PHP. So the same rules and priorities apply. It works in every Fluid context: in Extbase templates, in Fluid-based content elements, in components and in the page template of the site package.
- The argument property is the only required argument, for example description, og:title or og:type.
- With type you force name, property or http-equiv. Without type, the responsible manager decides, for example property for og tags.
- With subProperties you add extra details such as width, height or alt. For og:image, the manager turns them into og:image:width and og:image:height.
- Setting replace to true overwrites a meta tag that is already set. Without replace, the existing tag with the same property stays.
<f:page.meta property="description" replace="true">{concert.teaser}</f:page.meta>
<f:page.meta property="og:title">{concert.title}</f:page.meta>
<f:page.meta property="og:image" subProperties="{width: 1200, height: 630}">{imageUrl}</f:page.meta>Including CSS and JavaScript
The ViewHelpers f:asset.css and f:asset.script register CSS and JavaScript from Fluid with the AssetCollector. TYPO3 outputs everything collected in the right place of the page. You can give a file, with href for CSS and with src for JavaScript, or inline code as the content.
The identifier: The argument identifier is always required. If an asset with the same identifier is registered several times, for example because the slider sits in three content elements, TYPO3 outputs it only once. The same identifier means the same asset. So if two content elements register two different files under the identifier slider, only one of them appears, namely the one registered last. That is why each independent file needs a unique identifier.
<f:asset.css identifier="lindenau-main" href="EXT:lindenau_site/Resources/Public/Css/main.css" media="screen" />
<f:asset.script identifier="lindenau-slider" src="EXT:lindenau_site/Resources/Public/JavaScript/slider.js" defer="true" />
<div style="{f:asset.styleAttr(value: 'background-color: {instrument.color}')}">…</div>More arguments:
- Setting priority to true puts a stylesheet before the other CSS files. Included CSS files always go into the head. For a script, priority decides whether it goes into the head. Without priority, scripts end up at the end of the body. Watch out: TYPO3 also puts inline CSS without priority at the end of the body, although the argument description says CSS always goes into the head. This applies to code given as content and to files with inline set to true.
- Setting inline to true embeds the content of a file given with href or src directly into the page.
- The ViewHelper
f:asset.cssknows HTML attributes such as media, integrity and crossorigin. - The ViewHelper
f:asset.scriptknows async, defer, nomodule and type. With defer, the script only runs after the document has been parsed. With async, it is loaded in parallel and runs as soon as it arrives. With nomodule, it only runs in browsers without ES modules. - Since TYPO3 14.2, the former argument useNonce is called csp. It controls whether a hash or a nonce for the Content Security Policy is collected for the asset.
Values in style attributes: The ViewHelper f:asset.styleAttr exists since TYPO3 14.2. It returns the value for the style attribute of an HTML tag and collects a hash for the CSP directive style-src-attr. That way a single inline style stays allowed under a strict Content Security Policy. You still include external stylesheets with the ViewHelper f:asset.css.
Key points
- The ViewHelpers in the link group create an a tag, those in the uri group only the URL.
- The ViewHelpers
f:format.rawandf:format.htmlentitiesDecodecan lead to cross-site scripting. The ViewHelperf:format.htmluseslib.parseFunc_RTE. - For dates, pattern wins over format. Without either, SYS ddmmyy applies, by default Y-m-d. The locale only works with pattern.
- The ViewHelper
f:render.textneeds field with the database field name, and the content element needs record-transformation. - The ViewHelper
f:imagetakes image for FAL objects and src for paths, and it does not process external URLs. - The ViewHelper
f:image.srcsetexists since TYPO3 14.2. It knows w or x, and for x it needs referenceWidth. - Crop variants live in the TCA of the field crop. For a single content type you use columnsOverrides, to switch one off you use disabled.
- The ViewHelpers
f:page.headerDataandf:page.footerDataare new in TYPO3 14 and output unfiltered content. - The ViewHelper
f:page.metauses the MetaTagManager. It only overwrites tags that are already set when you use replace. - Asset ViewHelpers always need an identifier. The same identifier means only one asset.
Terms
- AssetCollector
- Collects CSS and JavaScript and outputs each asset only once per identifier.
- Crop variant
- A stored crop of an image with its own aspect ratio.
- Descriptor
- The value after each image URL in a srcset, either a width with w or a pixel density with x.
- FAL
- File Abstraction Layer, the file management of TYPO3 with File and FileReference objects.
- ICU
- A library for localized formats whose patterns the argument pattern uses.
- MetaTagManager
- The TYPO3 API that manages meta tags from TypoScript, PHP and Fluid.
- PageRenderer
- Builds the frame of the HTML page and takes in head and footer data.
- record-transformation
- A data processor that turns raw data into a record object that knows the TCA.