TYPO3 View­Hel­per erstellen: So geht’s

TYPO3 View­Hel­per werden ein­ge­setzt, um wie­der­ver­wend­ba­re Funk­tio­nen direkt in Fluid-Templates zu in­te­grie­ren. So lassen sich komplexe Daten ver­ar­bei­ten, Schleifen steuern und Be­din­gun­gen einfügen. Die Trennung von Logik und Prä­sen­ta­ti­on macht den Code war­tungs­freund­li­cher und optimiert die Per­for­mance.

Was ist ein TYPO3 View­Hel­per?

Ein TYPO3 View­Hel­per ist eine Funk­tio­na­li­tät innerhalb des TYPO3 CMS, die speziell für das Template-System Fluid ent­wi­ckelt wurde. TYPO3 Fluid ist das Standard-Tem­pla­ting-System, mit dem sich das Layout und die Struktur einer Webseite de­fi­nie­ren lassen. View­Hel­per erweitern Fluid um be­nut­zer­de­fi­nier­te Funk­tio­nen, die es erlauben, komplexe logische Ope­ra­tio­nen durch­zu­füh­ren.

Technisch gesehen handelt es sich bei einem View­Hel­per um eine PHP-Klasse, die eine bestimmte Funk­tio­na­li­tät kapselt. Diese Klasse kann dann in einem Fluid-Template durch spezielle Tags auf­ge­ru­fen werden, die als View­Hel­per-Tags bekannt sind. Ein View­Hel­per kann eine Vielzahl von Aufgaben über­neh­men, wie zum Beispiel die For­ma­tie­rung von Daten, das Einfügen von Be­din­gun­gen, das Erstellen von Schleifen oder das Abrufen von Inhalten aus Da­ten­ban­ken.

Wofür benötigt man einen TYPO3 View­Hel­per?

Ein zentraler Vorteil von View­Hel­pern ist, dass sie die Logik von der Prä­sen­ta­ti­on trennen. In modernen Web­ent­wick­lungs­prak­ti­ken hat sich die Methode bewährt, die Da­ten­ver­ar­bei­tung oder -ma­ni­pu­la­ti­on von der Dar­stel­lung zu se­pa­rie­ren. Dadurch bleibt der Code über­sicht­lich, wartbar und ska­lier­bar.

Ein weiterer wichtiger Vorteil von View­Hel­pern ist ihre Wie­der­ver­wend­bar­keit. Ein View­Hel­per kann einmalig definiert und dann an be­lie­bi­ger Stelle im Template oder sogar in mehreren Templates ein­ge­setzt werden. Ist bei­spiels­wei­se ein spe­zi­fi­sches Format für Da­tums­an­ga­ben er­for­der­lich, kann ein View­Hel­per einmal erstellt und dann in allen Templates ein­ge­setzt werden.

Typische An­wen­dungs­fäl­le für TYPO3 View­Hel­per sind:

• Da­ten­for­ma­tie­rung: Daten wie Datum, Zeit, Zahlen oder Währungen in das ge­wünsch­te Format bringen
• Be­din­gun­gen und Schleifen: Komplexe if-else-Abfragen oder Schleifen, die die Ausgabe des Templates steuern
• Da­ten­ab­fra­ge: Daten aus einer Datenbank abrufen und sie im Template dar­stel­len

Welche Standard-View­Hel­per gibt es?

Standard-View­Hel­per sind die vor­de­fi­nier­ten View­Hel­per, die in TYPO3 Fluid direkt zur Verfügung stehen. Sie gehören zur Stan­dard­bi­blio­thek von TYPO3 und bieten grund­le­gen­de Funk­tio­na­li­tä­ten, um Daten in Templates zu ma­ni­pu­lie­ren, Schleifen und Be­din­gun­gen um­zu­set­zen oder HTML-Elemente zu erzeugen. Die Standard-View­Hel­per lassen sich in mehrere Ka­te­go­rien einteilen.

Steuerung von Logik (Control Struc­tures)

Diese View­Hel­per er­mög­li­chen Be­din­gun­gen, Schleifen und Variablen-Handling:

• <f:if>: führt Inhalte basierend auf einer Bedingung aus
• <f:else>: al­ter­na­ti­ve Inhalte für <f:if>
• <f:for>: iteriert über eine Liste oder ein Array
• <f:alias>: definiert Variablen für einen be­stimm­ten Bereich

Beispiel:

<f:if condition="{variable} == 1">
    <p>Variable is 1</p>
<f:else>
    <p>Variable is not 1</p>
</f:if>

Da­ten­ma­ni­pu­la­ti­on

Diese TYPO3 View­Hel­per helfen, Werte oder Daten zu trans­for­mie­ren.

• <f:format.html>: kon­ver­tiert einen String in HTML
• <f:format.number>: for­ma­tiert eine Zahl
• <f:format.crop>: schneidet einen Text auf eine bestimmte Länge

Beispiel:

<f:format.number decimals="2">{price}</f:format.number>

Rendering und Layout

Es gibt View­Hel­per, die das Rendering von Partials, Layouts und Sections steuern.

• <f:render>: rendert ein Partial oder eine Section
• <f:layout>: definiert das über­ge­ord­ne­te Layout eines Templates
• <f:section>: markiert einen benannten Block innerhalb eines Templates

Beispiel:

<f:render partial="Product/Details" arguments="{product: product}" />

Formulare und Ein­ga­be­fel­der

Dies dient zum Erzeugen von HTML-For­mu­la­ren und For­mu­lar­ele­men­ten.

• <f:form>: erzeugt ein Formular
• <f:form.textfield>: erstellt ein Textfeld
• <f:form.checkbox>: erstellt eine Checkbox

Beispiel:

<f:form action="save">
    <f:form.textfield name="username" />
    <f:form.submit value="Save" />
</f:form>

Content Output

Diese TYPO3 View­Hel­per geben Inhalte oder Medien aus.

• <f:translate>: übersetzt einen Schlüssel in eine Sprache
• <f:debug>: gibt Debugging-In­for­ma­tio­nen aus
• <f:image>: rendert ein Bild mit op­tio­na­ler Ver­ar­bei­tung

Beispiel:

<f:translate key="welcomeMessage" />

View­Hel­per f:alias

f:alias ist ebenfalls ein TYPO3 View­Hel­per in Fluid. Er gehört zur Stan­dard­bi­blio­thek der Fluid-View­Hel­per und wird verwendet, um Werte oder komplexe Ausdrücke in Variablen um­zu­wan­deln, die dann im Template re­fe­ren­ziert werden können.

Der f:alias-View­Hel­per erlaubt es Ihnen, eine oder mehrere Variablen zu de­fi­nie­ren, die innerhalb eines be­stimm­ten Bereichs im Template verfügbar sind. Er nimmt eine map als Attribut, in der Sie die Variablen und ihre Werte de­fi­nie­ren. Die Variablen stehen nur innerhalb des Tags zur Verfügung, in dem der f:alias genutzt wird.

Syntax:

<f:alias map="{variableName: value}">
    <!-- variable can be used here -->
</f:alias>

Beispiel:

<f:alias map="{greeting: 'Hello, world!'}">
    <div>{greeting}</div>
</f:alias>

Ausgabe:

<div>Hello, world!</div>

Der f:alias-View­Hel­per kann auch für kom­ple­xe­re Logik verwendet werden, zum Beispiel um Er­geb­nis­se eines anderen View­Hel­pers zu speichern:

<f:alias map="{userImage: f:image(src: 'user.jpg', treatIdAsReference: true)}">
    <img src="{userImage}" alt="User image">
</f:alias>

Ausgabe:

<img src="path/to/user.jpg" alt="User image">

Be­nut­zer­de­fi­nier­te TYPO3 View­Hel­per: Anleitung zur Er­stel­lung und Nutzung

TYPO3 bietet bereits eine Vielzahl von Standard-View­Hel­pern, doch es gibt oft Szenarien, in denen be­nut­zer­de­fi­nier­te An­for­de­run­gen nicht durch diese Stan­dard­lö­sun­gen erfüllt werden können. In solchen Fällen ist es emp­feh­lens­wert, eigene View­Hel­per zu ent­wi­ckeln. Die Er­stel­lung eines eigenen View­Hel­pers erfolgt durch das Erstellen einer PHP-Klasse, die von \TYPO3\CMS\Fluid\Core\ViewHelper\AbstractViewHelper erbt. Darin wird dann die ge­wünsch­te Logik umgesetzt.

Das Ziel dieses Tutorials ist die Er­stel­lung eines be­nut­zer­de­fi­nier­ten TYPO3 View­Hel­pers, der es er­mög­licht, au­to­ma­tisch ein Gravatar-Bild für eine E-Mail-Adresse an­zu­zei­gen. Gravatar (Globally Re­co­gni­zed Avatar) ist ein weit ver­brei­te­ter Dienst, der mit einer E-Mail-Adresse ver­knüpf­te Avatare be­reit­stellt. Durch diesen View­Hel­per soll die In­te­gra­ti­on eines Gravatar-Bildes in Fluid-Templates so einfach wie möglich gestaltet werden.

Ein­satz­bei­spiel des View­Hel­pers in einem Fluid-Template

Der Gravatar-View­Hel­per wird fol­gen­der­ma­ßen in einem Fluid-Template verwendet:

<html
    xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
    xmlns:m="http://typo3.org/ns/MyVendor/MyExtension/ViewHelpers"
    data-namespace-typo3-fluid="true"
>
    <m:gravatar emailAddress="username@example.org" alt="Gravatar icon of user" />
</html>

Hierbei ist m ein Beispiel für den Namespace des be­nut­zer­de­fi­nier­ten View­Hel­pers. Das Präfix m gibt an, dass alle Elemente mit m: von den be­nut­zer­de­fi­nier­ten View­Hel­pern aus der Er­wei­te­rung MyVendor.MyExtension stammen. Mit diesem Ansatz kann der View­Hel­per in be­lie­bi­gen Templates ein­ge­setzt werden, ohne dass red­un­dan­ter Code ge­schrie­ben werden muss.

Er­stel­lung eines eigenen Fluid-View­Hel­pers

Die Ent­wick­lung eines be­nut­zer­de­fi­nier­ten TYPO3 View­Hel­pers erfordert die Er­stel­lung einer PHP-Klasse, die von der Ba­sis­klas­se AbstractViewHelper erbt. Diese Ba­sis­klas­se bietet grund­le­gen­de Funk­tio­na­li­tä­ten, wie die Re­gis­trie­rung von Ar­gu­men­ten und die Im­ple­men­tie­rung der Ren­der­lo­gik.

Der View­Hel­per wird ty­pi­scher­wei­se in einer TYPO3-Er­wei­te­rung unter Classes/ViewHelpers abgelegt. Der Name der Datei sollte mit dem Namen des View­Hel­pers über­ein­stim­men. Für unseren Gravatar-View­Hel­per wird eine Datei namens GravatarViewHelper.php angelegt.

Hier ist der voll­stän­di­ge Code der Klasse:

<?php
declare(strict_types=1);
namespace MyVendor\MyExtension\ViewHelpers;
use TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper;
final class GravatarViewHelper extends AbstractViewHelper
{
    protected $escapeOutput = false;
    public function initializeArguments(): void
    {
        // registerArgument($name, $type, $description, $required, $defaultValue, $escape)
        $this->registerArgument(
            'emailAddress',
            'string',
            'The email address to resolve the gravatar for',
            true,
        );
        $this->registerArgument(
            'alt',
            'string',
            'The optional alt text for the image',
        );
    }
    public function render(): string
    {
        $emailAddress = $this->arguments['emailAddress'];
        $altText = $this->arguments['alt'] ?? '';
        // this is improved with the TagBasedViewHelper (see below)
        return sprintf(
            '<img src="https://www.gravatar.com/avatar/%s" alt="%s">',
            md5($emailAddress),
            htmlspecialchars($altText),
        );
    }
}

• Namespace und Ba­sis­klas­se: Die Klasse befindet sich im Namespace MyVendor\MyExtension\ViewHelpers. Durch das Erben der AbstractViewHelper-Klasse können grund­le­gen­de Fluid-Funk­tio­nen wie die Ar­gu­ment­re­gis­trie­rung und die Render-Logik genutzt werden.

• initializeArguments: Diese Methode dient dazu, die Argumente zu de­fi­nie­ren, die der View­Hel­per erwartet. Im Fall des Gravatar-View­Hel­pers sind dies:

• emailAddress: Eine er­for­der­li­che E-Mail-Adresse, anhand derer das Gravatar-Bild generiert wird.

• alt: Ein op­tio­na­ler Al­ter­na­tiv­text, der im HTML-Tag für das Bild angegeben wird.

• registerArgument: Diese Methode definiert den Namen des Arguments (emailAddress oder alt), den Datentyp (string in beiden Fällen) und eine Be­schrei­bung, die für Do­ku­men­ta­ti­ons­zwe­cke verwendet wird, ob das Argument er­for­der­lich ist oder nicht.

• render: Die render-Methode enthält die Kernlogik des View­Hel­pers. Sie wird auf­ge­ru­fen, wenn der View­Hel­per im Template benutzt wird.

• E-Mail-Hashing: Die E-Mail-Adresse wird zuerst in Klein­buch­sta­ben um­ge­wan­delt und Leer­zei­chen werden entfernt. An­schlie­ßend wird ein MD5-Hash der be­rei­nig­ten E-Mail-Adresse erstellt. Dies ist er­for­der­lich, da Gravatar die Avatare anhand von MD5-Hashes der E-Mail-Adressen speichert.

• Gravatar-URL-Er­stel­lung: Der MD5-Hash wird an die URL https://www.gravatar.com/avatar/ angehängt, um die spe­zi­fi­sche Avatar-Bild­adres­se zu ge­ne­rie­ren.

• Rückgabe eines HTML-<img>-Tags: Der View­Hel­per gibt ein voll­stän­di­ges HTML-Bild-Tag zurück. Dabei wird die Gravatar-URL als src-Attribut benutzt und der Al­ter­na­tiv­text (falls angegeben) als alt-Attribut eingefügt. Der Text wird mit htmlspecialchars vor po­ten­zi­el­len XSS-Angriffen geschützt.

Ein Beispiel:

Wenn die E-Mail-Adresse username@example.org lautet, wird ihr MD5-Hash b58996c504c5638798eb6b511e6f49af berechnet. Die ge­ne­rier­te URL lautet dann:

https://www.gravatar.com/avatar/b58996c504c5638798eb6b511e6f49af

Das Resultat ist ein HTML-Tag:

<img src="https://www.gravatar.com/avatar/b58996c504c5638798eb6b511e6f49af" alt="Gravatar icon of user" />

Der einfache Gravatar-View­Hel­per, der bislang vor­ge­stellt wurde, erfüllt grund­le­gen­de An­for­de­run­gen, indem er die URL für ein Gravatar-Bild basierend auf einer E-Mail-Adresse generiert und als HTML-Tag zu­rück­gibt. Dennoch gibt es Mög­lich­kei­ten, ihn weiter aus­zu­bau­en, um zu­sätz­li­che Funk­tio­nen und eine bessere Fle­xi­bi­li­tät zu ge­währ­leis­ten.

Un­ter­stüt­zung für Bild­grö­ßen

Gravatar bietet die Mög­lich­keit, die Größe der an­ge­zeig­ten Avatare durch einen URL-Parameter an­zu­pas­sen. Um diese Funktion zu in­te­grie­ren, kann der TYPO3 View­Hel­per erweitert werden, sodass er ein Argument size ak­zep­tiert. Dieses Argument wird an die Gravatar-URL angehängt und erlaubt es, die ge­wünsch­te Pi­xel­grö­ße des Bildes fest­zu­le­gen.

Code-An­pas­sun­gen:

In der Methode initializeArguments wird ein neues Argument hin­zu­ge­fügt:

$this->registerArgument('size', 'int', 'size of Gravatar image in pixels', false, 80);

Der Stan­dard­wert für die Bildgröße beträgt 80 Pixel. In der render-Methode wird dieses Argument verwendet, um die URL zu erweitern:

$size = $this->arguments['size'];
$gravatarUrl .= "?s=" . intval($size);

Durch diese Ergänzung können Be­nut­ze­rin­nen und Benutzer die Größe des Bildes im Template wie folgt festlegen:

<m:gravatar emailAddress="user@example.org" size="200" />

Umgang mit Stan­dard­bil­dern

Sie können ein Stan­dard­bild auswählen, das angezeigt wird, wenn keine Gravatar-In­for­ma­tio­nen für eine E-Mail-Adresse vorhanden sind. Stan­dard­bil­der können entweder über eine URL oder als vor­de­fi­nier­te Gravatar-Optionen wie mp, identicon, wavatar, retro oder robohash angegeben werden.

Um diese Funk­tio­na­li­tät zu in­te­grie­ren, wird ein weiteres Argument defaultImage hin­zu­ge­fügt:

$this->registerArgument('defaultImage', 'string', 'URL or Gravatar option for a standard image', false, 'mp');

Innerhalb der render-Methode wird das Argument ver­ar­bei­tet:

$defaultImage = $this->arguments['defaultImage'];
$gravatarUrl .= "&d=" . urlencode($defaultImage);

So können die Be­nut­ze­rin oder der Benutzer ein Stan­dard­bild für Avatare angeben:

<m:gravatar emailAddress="user@example.org" defaultImage="identicon" />

Er­wei­te­rung um zu­sätz­li­che Parameter

Gravatar un­ter­stützt weitere Parameter wie das Festlegen eines Ratings (rating) oder die De­fi­ni­ti­on einer Ab­wei­chungs­kon­trol­le (forceDefault). Um den TYPO3 View­Hel­per flexibler zu gestalten, können auch diese Optionen als Argumente hin­zu­ge­fügt werden. Bei­spiels­wei­se könnte ein rating-Argument re­gis­triert werden:

$this->registerArgument('rating', 'string', 'Age rating of Gravatar image (g, pg, r, x)', false, 'g');

Die re­sul­tie­ren­de URL würde dann auch dieses Argument enthalten:

$rating = $this->arguments['rating'];
$gravatarUrl .= "&r=" . urlencode($rating);

Schutz vor Cross-Site-Scripting (XSS)

Um dafür zu sorgen, dass der ge­ne­rier­te HTML-Code sicher ist, wird die Funktion htmlspecialchars ein­ge­setzt, um Benutzer-Eingaben zu ent­schär­fen. Dies ver­hin­dert, dass bösartige Skripte in das Template ein­ge­bet­tet werden können. Bei­spiels­wei­se wird das alt-Attribut so behandelt:

return sprintf('<img src="%s" alt="%s" />', $gravatarUrl, htmlspecialchars($alt));

Va­li­die­rung der Argumente

Eine gute Praxis besteht darin, Eingaben vor der Ver­ar­bei­tung zu va­li­die­ren. Zum Beispiel kann die Größe (size) auf einen sinn­vol­len Bereich ein­ge­schränkt werden, um un­vor­her­seh­ba­res Verhalten zu vermeiden:

$size = max(1, min(2048, intval($this→arguments['size'])));

Mit solchen Schutz­maß­nah­men bleibt der TYPO3 View­Hel­per robust gegenüber feh­ler­haf­ten oder po­ten­zi­ell schäd­li­chen Eingaben.

compile()-Methode

Die Methode compile() wird verwendet, um den View­Hel­per für eine direkte PHP-Aus­füh­rung zu kom­pi­lie­ren. Sie eignet sich, wenn der View­Hel­per lediglich eine Wrapper-Funktion für native PHP-Funk­tio­nen ist. Dies eli­mi­niert die Not­wen­dig­keit, den View­Hel­per voll­stän­dig aus­zu­füh­ren und erhöht die Leistung.

Hier ist ein TYPO3 View­Hel­per, der eine Zei­chen­ket­te in Klein­buch­sta­ben umwandelt:

<?php
namespace MyVendor\BlogExample\ViewHelpers;
use TYPO3Fluid\Fluid\Core\Compiler\TemplateCompiler;
use TYPO3Fluid\Fluid\Core\Parser\SyntaxTree\ViewHelperNode;
use TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper;
final class StrtolowerViewHelper extends AbstractViewHelper
{
    public function initializeArguments(): void
    {
        $this->registerArgument('string', 'string', 'The string to lowercase.', true);
    }
    public function compile(
        $argumentsName,
        $closureName,
        &$initializationPhpCode,
        ViewHelperNode $node,
        TemplateCompiler $compiler
    ): string {
        return sprintf("strtolower(%s['string'])", $argumentsName);
    }
}

Migration von renderStatic()

Die Methode renderStatic() wurde in TYPO3 v12 und Fluid v2.15 als veraltet markiert. Sie wurde häufig zusammen mit den Traits CompileWithRenderStatic oder CompileWithContentArgumentAndRender verwendet. Die Migration auf render() ist notwendig, um mit der neuesten TYPO3-Version kom­pa­ti­bel zu sein.

Vorher:

public static function renderStatic(array $arguments, \Closure $renderChildrenClosure, RenderingContextInterface $renderingContext): string
{
    $emailAddress = $arguments['emailAddress'];
    return sprintf('<img src="https://www.gravatar.com/avatar/%s">', md5($emailAddress));
}

Nachher:

public function render(): string
{
    $emailAddress = $this->arguments['emailAddress'];
    return sprintf('<img src="https://www.gravatar.com/avatar/%s">', md5($emailAddress));
}

Entfernen von CompileWithContentArgumentAndRenderStatic

Falls der Trait CompileWithContentArgumentAndRenderStatic genutzt wurde, muss die Logik angepasst werden. Statt renderChildrenClosure() wird die Methode $this->renderChildren() ein­ge­setzt.

Vorher:

$emailAddress = $renderChildrenClosure();

Nachher:

$emailAddress = $this→renderChildren();

Ersatz von renderStatic()-Aufrufen

Falls ein TYPO3 View­Hel­per einen anderen View­Hel­per durch dessen renderStatic()-Methode auf­ge­ru­fen hat, muss dies durch den Einsatz von invoke() angepasst werden.

Vorher:

$gravatorUrl = GravatarUrlViewHelper::renderStatic(['email', $emailAddress], $renderChildrenClosure, $renderingContext);

Nachher:

$gravatarUrl = $this->renderingContext->getViewHelperInvoker()->invoke(
    GravatarUrlViewHelper::class,
    ['email' => $emailAddress],
    $this->renderingContext,
    $this->renderChildren(),
);

TYPO3 ist ein CMS mit großer Funk­ti­ons­viel­falt. Eine Anleitung zur TYPO3-In­stal­la­ti­on und wie Sie eine TYPO3-Webseite erstellen können, finden Sie in separaten Ratgebern.