Lernseite · Fluid-Grundlagen
Fluid verstehen: Templates, Variablen, ViewHelper und Components
Fluid ist die Template-Engine von TYPO3. Auf dieser Seite baust du mit der Integratorin Mara die Templates für die Website einer Musikschule. Danach weißt du, wie Templates, Layouts und Partials zusammenspielen, wie du Variablen sicher ausgibst und wie ViewHelper, Components und die Fluid-Befehle funktionieren.
Was Fluid ist
Mara baut die Website der Musikschule Lindenau. Das Projekt ist eine Composer-Installation mit TYPO3 14.3. Das Aussehen steckt in ihrem eigenen Sitepackage lindenau_site, das Composer-Paket heißt lindenau/site.
Fluid erzeugt aus Templates und Daten eine Ausgabe, meistens HTML. Es ist ein eigenständiges Open-Source-Projekt, das TYPO3 für das Frontend und für das Backend nutzt. Im Muster Model-View-Controller ist Fluid die View, also die Darstellungsschicht. Das Model hält die Daten. Der Controller verarbeitet die Anfrage und gibt die Daten an die View weiter.
Seit Fluid 5, das mit TYPO3 14 kommt, ist die Dateiendung fluid.html üblich, etwa Default.fluid.html. Sie ist freiwillig, Dateien mit der Endung html werden weiter gefunden. Gibt es beide im selben Ordner, gewinnt die Datei mit fluid.html.
Templates, Layouts und Partials
Fluid kennt drei Arten von Dateien. Gerendert wird immer ein Template. Es ist der Startpunkt und deshalb Pflicht. Layouts und Partials sind freiwillig.
- Ein Layout ist der Rahmen um viele Templates. Bei Mara enthält es Kopf und Fuß der Seite.
- Ein Template füllt diesen Rahmen. Es wählt sein Layout mit dem ViewHelper
f:layoutund legt seinen Inhalt in Sections ab, also benannte Abschnitte mitf:section. - Ein Partial ist ein kleiner, wiederverwendbarer Baustein, zum Beispiel ein Teaser für einen Kurs.
Das Layout setzt die Sections des Templates mit f:render ein. Ein Layout darf selbst nur Sections und Partials rendern, aber keine eigenen Sections definieren. Templates und Partials dürfen beides.
<!-- Layouts/Default.fluid.html -->
<header>Musikschule Lindenau</header>
<main><f:render section="Main" /></main>
<footer>Lindenauer Markt 4</footer>
<!-- Templates/Pages/Default.fluid.html -->
<f:layout name="Default" />
<f:section name="Main">
<h1>{page.title}</h1>
<f:render partial="Course/Teaser" arguments="{course: course}" />
</f:section>Wer sieht welche Variablen?
- Das Layout arbeitet mit denselben Variablen wie das Template, das es nutzt.
- Ein Partial ist abgeschlossen. Es sieht nur das, was das Template beim Einbinden mit dem Argument
argumentsübergibt. Mit dem besonderen Wert_allübergibst du alle Variablen auf einmal.
Eine Ausnahme kennt der Code von Fluid 5: Die Variable settings reicht Fluid automatisch an Partials weiter, wenn du keine eigene Variable mit diesem Namen übergibst. Alle anderen Variablen musst du ausdrücklich übergeben.
Auch ein Partial kann Sections haben. Mit f:render und den Argumenten partial und section zugleich renderst du gezielt eine Section aus einem Partial. Partials dürfen ihrerseits weitere Partials rendern.
Wo Fluid die Dateien findet
Die Pfade zu den Dateien stehen in drei Listen: templateRootPaths, layoutRootPaths und partialRootPaths. Jeder Eintrag hat eine Zahl als Schlüssel. Fluid prüft die Pfade von hinten: Der höchste Schlüssel wird zuerst durchsucht, der niedrigste zuletzt. Die erste passende Datei gewinnt.
Mara nutzt ein Basis-Paket ihrer Agentur unter dem Schlüssel 10 und ihr Sitepackage unter dem Schlüssel 20. Beide enthalten eine Datei Default.fluid.html. Fluid nimmt die Datei aus Pfad 20. So überschreibt Mara gezielt einzelne Dateien. Es gibt keinen Fehler, und es werden nicht beide Dateien gerendert.
In jedem Pfad probiert Fluid zuerst die Endung fluid.html, dann html, dann keine Endung. Diese Kette läuft je Pfad. Eine alte Datei mit der Endung html in Pfad 20 schlägt also eine Datei mit fluid.html in Pfad 10.
Variablen ausgeben
Eine Variable gibst du aus, indem du ihren Namen in geschweifte Klammern setzt. Auf Unterwerte greifst du mit einem Punkt zu. Das gilt für Array-Schlüssel und für Eigenschaften von Objekten. Pfeile oder eckige Klammern wie in PHP gibt es dafür nicht.
<h1>{title}</h1>
<p>{course.name}, bei {course.teacher.name}</p>
<p>Preis: {prices.{duration}} Euro</p>Wie kommt Fluid an die Eigenschaft eines Objekts? Für den Namen eines Kurses probiert Fluid nacheinander die Methoden getName(), isName() und hasName() und zuletzt den direkten Zugriff auf die Eigenschaft name. Auch Objekte mit ArrayAccess und Container nach dem PSR-Standard ContainerInterface funktionieren. Findet Fluid nichts, bleibt die Ausgabe still leer.
Dynamische Schlüssel: Steht der Schlüssel selbst in einer Variable, schachtelst du geschweifte Klammern ineinander, wie in der dritten Zeile oben. Ohne die inneren Klammern würde Fluid den festen Schlüssel duration lesen und nicht den Wert der Variable.
Reservierte Namen: Die Namen _all, true, false und null darfst du nicht für eigene Variablen verwenden. Seit Fluid 5 gilt das für alle Variablennamen, die mit einem Unterstrich beginnen. Das betrifft nur den ersten Teil des Namens. Ein Array-Schlüssel oder eine Eigenschaft mit Unterstrich nach dem Punkt bleibt erlaubt.
<!-- ungültig seit Fluid 5 -->
{_temp}
{_somethingElse}
<!-- gültig -->
{data._something}
{myArray._myKey}
{items.{index}}Sicher ausgeben: Escaping
Fluid maskiert jede Variable standardmäßig mit der PHP-Funktion htmlspecialchars. Aus einem Script-Tag wird so harmloser Text, der im Browser sichtbar ist, aber nicht ausgeführt wird. Das schützt vor Cross-Site Scripting, kurz XSS. Das Escaping hängt nicht von der Dateiendung ab. Es gilt auch in Templates für Text-Mails oder JSON.
Manchmal brauchst du ungefiltertes HTML. Dafür gibt es zwei ViewHelper:
f:format.rawschaltet das Escaping für einen Wert ganz ab. Das ist nur für HTML gedacht, das schon sicher ist.f:format.htmlist für Text aus dem Rich-Text-Editor gedacht. Er schickt den Text durch parseFunc, das Links umwandelt und nur erlaubte Tags durchlässt.
HTML-Kommentare schützen nicht. Für Fluid ist ein HTML-Kommentar normaler Text. Variablen und ViewHelper darin werden ausgewertet und ausgeführt. Ein Debug-Aufruf in einem HTML-Kommentar läuft also trotzdem. Nur der ViewHelper f:comment entfernt Inhalte wirklich.
JavaScript und CSS im Template: Alpine.js und CSS nutzen ebenfalls geschweifte Klammern. Fluid würde sie als Variablen lesen. Seit Fluid 5 hilft ein CDATA-Abschnitt. Darin ignoriert Fluid ViewHelper-Tags und einfache geschweifte Klammern. Ausgewertet werden nur Ausdrücke in drei geschweiften Klammern. Die CDATA-Markierung selbst entfernt Fluid aus der Ausgabe.
<![CDATA[
<div x-data="{ open: false }">
<button @click="open = !open">{{{label}}}</button>
</div>
]]>Früher hat Fluid CDATA-Abschnitte samt Inhalt entfernt, und manche nutzten sie zum Auskommentieren. Das geht seit TYPO3 14 nicht mehr.
ViewHelper und Namensräume
ViewHelper sind die Bausteine, mit denen ein Template Daten verarbeitet oder ausgibt. Hinter jedem ViewHelper steht eine PHP-Klasse. Bei Components ist es stattdessen ein Fluid-Template.
Die mitgelieferten ViewHelper haben das Präfix f, etwa f:for, f:if oder f:link.page. Dieser Namensraum ist immer verfügbar, du musst ihn nicht importieren.
Jeden ViewHelper kannst du auf zwei Arten schreiben: als Tag wie HTML oder inline in geschweiften Klammern. Inline lassen sich ViewHelper mit einem Pfeil verketten, dann wird der Wert von links nach rechts weitergereicht.
<f:format.date format="d.m.Y">{course.start}</f:format.date>
{f:format.date(date: course.start, format: 'd.m.Y')}
{course.title -> f:format.trim()}Fremde ViewHelper importieren: Für ViewHelper einer anderen Extension brauchst du eine Namespace-Deklaration. Sie verknüpft ein Präfix mit einem PHP-Namensraum. Es gibt drei Wege:
- Am html-Tag mit einem xmlns-Attribut. Das ist XML-konform, und IDEs können damit Tags vorschlagen. Das zusätzliche Attribut
data-namespace-typo3-fluidmit dem Wert true sorgt dafür, dass das html-Tag selbst nicht ausgegeben wird. - Mit der kurzen Schreibweise in geschweiften Klammern, die mit dem Wort namespace beginnt.
- Global in der Datei
Namespaces.phpim OrdnerConfiguration/Fluideiner Extension. Dann ist das Präfix in allen Templates ohne Import verfügbar.
<html xmlns:ls="http://typo3.org/ns/Lindenau/Site/ViewHelpers"
data-namespace-typo3-fluid="true">
{namespace news=GeorgRinger\News\ViewHelpers}Die Adresse im xmlns-Attribut beginnt immer mit http, nicht mit https. Mit https bricht Fluid mit einem Fehler ab, weil die Namespace-Deklaration ungültig ist.
Globale Namensräume seit TYPO3 14: Früher trug man globale Namensräume in die Systemkonfiguration ein, unter SYS, fluid und namespaces in den TYPO3_CONF_VARS. Das ist seit TYPO3 14.1 veraltet. Heute liefert jede Extension die Datei Namespaces.php.
<?php
// EXT:lindenau_site/Configuration/Fluid/Namespaces.php
return [
'ls' => ['Lindenau\\Site\\ViewHelpers'],
'lc' => ['Lindenau\\Site\\Components'],
];Registrieren zwei Extensions denselben Namensraum, führt TYPO3 die Dateien in der Ladereihenfolge zusammen. Es gibt keinen Fehler, und nichts wird ignoriert. Hängt Extension 2 von Extension 1 ab, wird sie später geladen, und ihre gleichnamigen ViewHelper gewinnen. So überschreibt eine Extension gezielt einzelne ViewHelper einer anderen.
Bedingungen und Schleifen
Bedingungen: Der ViewHelper f:if gibt Inhalte nur aus, wenn seine Bedingung zutrifft. Mit f:then und f:else legst du fest, was im jeweiligen Fall erscheint. Für mehrere Fälle nacheinander musst du nicht verschachteln: Innerhalb von f:if kannst du mehrere f:else mit eigenem Argument if angeben. Ein letztes f:else ohne if fängt den Rest ab.
<f:if condition="{course.full}">
<f:then>Warteliste</f:then>
<f:else if="{course.freeSeats} < 3">Fast voll</f:else>
<f:else>Plätze frei</f:else>
</f:if>
<a class="{f:if(condition: isActive, then: 'active', else: '')}">Klavier</a>Die Inline-Schreibweise in der letzten Zeile übergibt condition, then und else als Argumente. Sie eignet sich gut für CSS-Klassen in Attributen.
Schleifen: Der ViewHelper f:for durchläuft eine Liste und gibt seinen Inhalt für jedes Element aus. Er kennt fünf Argumente:
- each ist die Liste und as der Name, unter dem das aktuelle Element bereitsteht. Beide sind Pflicht.
- key legt den Namen einer Variable für den Schlüssel fest, etwa bei einem assoziativen Array.
- reverse mit dem Wert true durchläuft die Liste rückwärts.
- iteration legt den Namen für ein Objekt mit Zählwerten fest.
Das iteration-Objekt liefert sieben Werte: index zählt ab 0, cycle zählt ab 1, total ist die Anzahl der Elemente. isFirst und isLast sagen, ob das Element das erste oder letzte ist, isEven und isOdd, ob cycle gerade oder ungerade ist. Ein vorheriges oder nächstes Element liefert es nicht.
<f:for each="{courses}" as="course" key="id" iteration="i">
<p>{i.cycle}. {id}: {course.name}</p>
<f:if condition="{i.cycle} % 3 == 0 && !{i.isLast}">
<hr>
</f:if>
</f:for>Partials und Sections rendern, Argumente festlegen
Der ViewHelper f:render bindet Partials und Sections ein. Seine wichtigsten Argumente:
- partial lädt ein Partial, section eine Section. Beide zusammen rendern eine Section aus einem Partial.
- arguments übergibt Variablen, etwa den Kurs oder mit
_allalle Variablen. - optional mit dem Wert true sorgt dafür, dass eine fehlende Section keinen Fehler auslöst. Die Ausgabe bleibt dann leer. Das ist für Sections gedacht, die nicht jedes Template definiert, etwa eine Seitenleiste.
- default liefert einen Ersatztext, wenn die Ausgabe leer bleibt, zum Beispiel weil eine optionale Section fehlt.
- contentAs macht den Inhalt zwischen öffnendem und schließendem Tag zu einer Variable im Partial.
<f:render section="Sidebar" optional="true" />
<f:render partial="Box" arguments="{title: 'Anmeldung'}" contentAs="content">
<p>Anmeldeschluss ist der 30. September.</p>
</f:render>Argumente deklarieren: Mit dem ViewHelper f:argument legt ein Template, ein Partial oder eine Component fest, welche Variablen es erwartet. Pflicht sind nur name und type. Freiwillig sind description, optional und default.
<f:argument name="course" type="Lindenau\Site\Domain\Model\Course" />
<f:argument name="size" type="string" optional="{true}" default="m" />- Ohne optional ist ein Argument Pflicht. Fehlt es beim Aufruf, wirft Fluid einen Fehler.
- Der Typ wird bei der Übergabe geprüft. Passt der Wert nicht und lässt er sich nicht umwandeln, gibt es ebenfalls einen Fehler.
- default greift nur bei optionalen Argumenten. Ein Standardwert macht ein Pflicht-Argument nicht optional.
Components: Bausteine mit fester Schnittstelle
Die Kurskarte der Musikschule erscheint auf vielen Seiten. Dafür sind Fluid Components gedacht. Sie sind wiederverwendbare Bausteine aus Fluid-Templates, die man wie eigene HTML-Tags nutzt. Eine eigene PHP-Klasse je Component braucht man nicht.
Gegenüber Partials haben Components zwei Vorteile. Erstens brauchen sie keine partialRootPaths im aufrufenden Kontext. Zweitens haben sie feste, typisierte Argumente, die du mit f:argument deklarierst. Für Components sind diese Deklarationen die öffentliche Schnittstelle und deshalb erforderlich.
Wann Component, wann Partial, wann Section? Für einen Baustein, den du überall brauchst, nimm eine Component. Für einen Teil, der nur innerhalb eines Templates vorkommt, reicht eine Section.
Die Einrichtung: Vor der ersten Component braucht es eine Component Collection. Sie verknüpft einen Ordner mit Templates mit einem PHP-Namensraum. Früher war dafür immer eine eigene PHP-Klasse nötig, meist auf Basis von AbstractComponentCollection, etwa in TYPO3 13. Seit TYPO3 14.1 reicht ein Eintrag in der Datei ComponentCollections.php im Ordner Configuration/Fluid. Die Klasse brauchst du nur noch für Sonderfälle.
<?php
// EXT:lindenau_site/Configuration/Fluid/ComponentCollections.php
return [
'Lindenau\\Site\\Components' => [
'templatePaths' => [
10 => 'EXT:lindenau_site/Resources/Private/Components',
],
],
];Standardmäßig liegt jede Component in einem eigenen Ordner. So kannst du CSS und JavaScript direkt neben ihr Template legen. Mara ordnet ihre Components nach Atomic Design, also nach Komplexität: kleine Atoms wie ein Button, Molecules wie die Kurskarte, große Organisms wie der Seitenkopf. Unterordner sprichst du im Tag-Namen mit einem Punkt an.
Eine Component deklariert ihre Argumente und nimmt mit dem ViewHelper f:slot den Inhalt auf, der beim Aufruf zwischen ihren Tags steht.
<!-- Components/Molecule/CourseCard/CourseCard.fluid.html -->
<f:argument name="title" type="string" />
<f:argument name="variant" type="string" optional="{true}" default="default" />
<article class="card card--{variant}">
<h3>{title}</h3>
<f:slot />
</article>
<!-- Aufruf in einem Template -->
<lc:molecule.courseCard title="Klavier für Kinder">
Ab 6 Jahren, dienstags 15 Uhr.
</lc:molecule.courseCard>Die Schnittstelle ist streng. Eine Component sieht keine Variablen des aufrufenden Templates. Sie kommuniziert nur über ihre Argumente und Slots. Einzige Ausnahme im Code ist wie bei Partials die Variable settings. Übergibt Mara beim Aufruf zusätzlich ein Argument class, das die Component nicht deklariert, wird es standardmäßig nicht angenommen, und Fluid meldet einen Fehler. Erlauben kann das nur die Component Collection, mit der Option additionalArgumentsAllowed.
Grenzen: Manche ViewHelper suchen ihren Eltern-ViewHelper im Rendering-Kontext. Ein Textfeld mit f:form.textfield braucht zum Beispiel das umgebende f:form. Eine Component hat aber einen eigenen Kontext. Darum funktionieren solche ViewHelper über Component-Grenzen hinweg nicht zuverlässig. Components sollen ohne Seiteneffekte auskommen.
Fehler finden: Kommentare, Debug und Kommandozeile
Kommentare: Ein Kommentar, der nicht im HTML landen soll, gehört in den ViewHelper f:comment. Sein Inhalt wird nicht geparst und erscheint nie in der Ausgabe. Darum kannst du damit auch ungültige Fluid-Syntax vorübergehend ausblenden. Ein HTML-Kommentar landet dagegen im Quelltext der Seite, und Fluid führt den Code darin aus.
<f:comment>
Neue Kurskarte, noch in Arbeit:
<lc:molecule.courseKarte title="{course.title}"
</f:comment>Debuggen: Welche Variablen im Template verfügbar sind, zeigt dir der ViewHelper f:debug. Mit der Variable _all als Inhalt siehst du alles auf einmal. Die Ausgabe ist ein aufklappbarer Baum mit Titel. Gegenüber einer schlichten Ausgabe mit echo oder var_dump hat das Vorteile: maxDepth begrenzt die Tiefe, standardmäßig auf 8, und du kannst bestimmte Klassen oder Eigenschaften ausblenden. PHP-Code gehört ohnehin nicht in Fluid-Templates.
Standardmäßig setzt f:debug seine Ausgabe an den Anfang der Seite. Mit dem Argument inline und dem Wert true erscheint sie an der Stelle des Tags. Mit title gibst du der Ausgabe eine Überschrift.
<f:debug title="Kursliste" inline="true">{_all}</f:debug>Fluid auf der Kommandozeile: TYPO3 bringt vier Befehle im Namensraum fluid mit. Einen Befehl zum Reparieren gibt es nicht.
- fluid:analyze prüft die Templates des Projekts auf Syntaxfehler und veraltete Funktionen, also Deprecations. Es meldet zum Beispiel Variablen, die mit einem Unterstrich beginnen.
- fluid:cache:warmup kompiliert die gefundenen Templates im Voraus. Das lohnt sich nach einem Deployment, damit der erste Besucher nicht warten muss, bis Fluid die Templates übersetzt hat.
- fluid:namespaces listet die global registrierten Namensräume.
- fluid:schema:generate schreibt XSD-Dateien für alle verfügbaren ViewHelper in den Ordner
var/transient. Seit TYPO3 14.2 gehören auch Components dazu. Deine IDE schlägt damit Tags und Argumente vor.
vendor/bin/typo3 fluid:analyze
vendor/bin/typo3 fluid:cache:warmupDas Wichtigste in Kürze
- Fluid ist die Template-Engine von TYPO3 und im MVC-Muster die View.
- Gerendert wird immer ein Template. Das Layout ist der Rahmen, Partials sind wiederverwendbare Teile.
- Das Layout sieht alle Variablen des Templates. Ein Partial bekommt nur, was du mit arguments übergibst, mit Ausnahme von settings.
- Der höchste Schlüssel in den Root-Pfaden wird zuerst durchsucht.
- Fluid maskiert jede Ausgabe. Der Raw-ViewHelper hebt das auf und ist bei Eingaben von Besuchern eine XSS-Lücke.
- Seit Fluid 5 sind Variablennamen mit führendem Unterstrich reserviert, und CDATA mit drei geschweiften Klammern trennt Fluid von JavaScript.
- Globale Namensräume registriert eine Extension seit TYPO3 14.1 in der Datei Namespaces.php.
- Components haben feste, typisierte Argumente, nehmen Inhalt über einen Slot auf und brauchen keine Partial-Pfade.
- Der Comment-ViewHelper entfernt Inhalte vor dem Parsen, ein HTML-Kommentar nicht.
- fluid:analyze prüft, fluid:cache:warmup kompiliert vor, fluid:schema:generate erzeugt XSD-Dateien.
Begriffe
- Component
- Wiederverwendbarer Baustein aus einem Fluid-Template mit festen Argumenten, der wie ein eigenes Tag genutzt wird.
- Component Collection
- Verknüpft einen Ordner mit Components mit einem Namensraum, seit TYPO3 14.1 auch per Konfigurationsdatei.
- Escaping
- Maskieren von HTML-Sonderzeichen, damit Text nicht als Code ausgeführt wird.
- Layout
- Rahmen aus gemeinsamem Markup, der die Sections eines Templates einsetzt.
- Partial
- Kleiner, wiederverwendbarer Teil, der nur übergebene Variablen sieht.
- Section
- Benannter Abschnitt in einem Template oder Partial.
- Slot
- Stelle in einer Component, an der der Inhalt zwischen ihren Tags erscheint.
- ViewHelper
- Baustein in einem Template, der Daten verarbeitet oder ausgibt, meist eine PHP-Klasse.
- XSD
- Schema-Datei, mit der eine IDE Tags und Argumente vorschlägt.
- XSS
- Cross-Site Scripting, eingeschleuster Schadcode im Browser.