Developing a custom ViewHelper

AbstractViewHelper

line 9 extends AbstractViewHelper

Every ViewHelper must inherit from the class \TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper .

A ViewHelper can also inherit from subclasses of \AbstractViewHelper , for example from \TYPO3Fluid\Fluid\Core\ViewHelper\AbstractTagBasedViewHelper . Several subclasses are offering additional functionality. The \AbstractTagBasedViewHelper will be explained later on in this chapter in detail.

Disable escaping the output

line 11 protected $escapeOutput = false;

By default, all output is escaped by htmlspecialchars() to prevent cross site scripting.

Setting the property $escapeOutput to false is necessary to prevent escaping of ViewHelper output.

By setting the property $escapeChildren to false, escaping of the tag content (its child nodes) can be disabled. If this is not set explicitly, the value will be determined automatically: If $escapeOutput: is true, $escapeChildren will be disabled to prevent double escaping. If $escapeOutput: is false, $escapeChildren will be enabled unless disabled explicitly.

Passing in children is explained in Prepare ViewHelper for inline syntax.

initializeArguments()

line 13 public function initializeArguments(): void

The Gravatar ViewHelper must hand over the email address which identifies the Gravatar. An alt text for the image is passed as optional parameter.

ViewHelpers have to register (line 16, $this->registerArgument()) parameters. The registration happens inside method initializeArguments().

In the example above, the ViewHelper receives the argument emailAddress (line 17) of type string (line 18) which is mandatory (line 19). The optional argument alt is defined in lines 22-26.

These arguments can be accessed through the array $this->arguments, in method render().

render()

line 29 public function render(): string

The method render() is called once the ViewHelper is rendered. Its return value can be directly output in Fluid or passed to another ViewHelper.

In line 30 an 31 we retrieve the arguments from the $arguments class property. alt is an optional argument and therefore nullable. Fluid ensures, the declared type is passed for non-null values. These arguments can contain user input.

When escapting is diabled, the render() method is responsible to prevent XSS attacks.

Therefore all arguments must be sanitized before they are returned.

Passing the email address through md5() ensures that we only have a hexadecimal number, it can contain no harmful chars.

The alt text is passed through htmlspecialchars(), therefore potentially harmful chars are escaped.

AbstractTagBasedViewHelper

line 6 class GravatarViewHelper extends AbstractTagBasedViewHelper

The ViewHelper does not inherit directly from \AbstractViewHelper but from \AbstractTagBasedViewHelper , which provides and initializes the \TagBuilder and passes on and escapes arbitrary tag attributes.

$tagName

line 9 protected $tagName = 'img';

There is a class property $tagName which stores the name of the tag to be created (<img>).

$this->tag->addAttribute()

line 28 - 31 $this->tag->addAttribute(...)

The tag builder is available as class property $this->tag. It offers the method TagBuilder::addAttribute() to add new tag attributes. In our example the attribute src is added to the tag.

$this->tag->render()

line 32 return $this->tag->render();

The GravatarViewHelper creates an img tag builder, which has a method named render(). After configuring the tag builder instance, the rendered tag markup is returned.

$this->registerTagAttribute()

 public function initializeArguments(): void
 {
     parent::initializeArguments();
+    $this->registerUniversalTagAttributes();
+    $this->registerTagAttribute('alt', 'string', 'Alternative Text for the image');
 }

 public function initializeArguments(): void
 {
     parent::initializeArguments();
+    // TODO: Remove registerUniversalTagAttributes and registerTagAttribute
+    // On dropping TYPO3 v12.4 support.
     $this->registerUniversalTagAttributes();
     $this->registerTagAttribute('alt', 'string', 'Alternative Text for the image');
 }

compile()-Method

This method can be overwritten to define how the ViewHelper should be compiled. That can make sense if the ViewHelper itself is a wrapper for another native PHP function or TYPO3 function. In that case, the method can return the call to this function and remove the need to call the ViewHelper as a wrapper at all.

The compile() has to return the compiled PHP code for the ViewHelper. Also the argument $initializationPhpCode can be used to add further PHP code before the execution.

Example implementation:

<?php

declare(strict_types=1);

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);
    }
}

renderStatic() method

render() method

Most of the time, this method is implemented.

Migration: Remove deprecated trait CompileWithRenderStatic

To remove the deprecated trait \TYPO3Fluid\Fluid\Core\ViewHelper\Traits\CompileWithRenderStatic switch to use the render() method instead of the renderStatic().

 <?php

 declare(strict_types=1);

 namespace MyVendor\MyExtension\ViewHelpers;

-use TYPO3Fluid\Fluid\Core\Rendering\RenderingContextInterface;
 use TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper;
-use TYPO3Fluid\Fluid\Core\ViewHelper\Traits\CompileWithRenderStatic;

 final class GravatarViewHelper extends AbstractViewHelper
 {
-    use CompileWithRenderStatic;
-
     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);
     }

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

line 13

Remove the trait \CompileWithRenderStatic .

lines 23, 24

Switch the render method from renderStatic() to render().

lines 25, 26

Fetch the arguments from the class property instead method argument.

Migration: Remove deprecated trait CompileWithContentArgumentAndRenderStatic

If \TYPO3Fluid\Fluid\Core\ViewHelper\Traits\CompileWithContentArgumentAndRender was also used in your ViewHelper implementation, further steps are needed:

 <?php

 declare(strict_types=1);

 namespace MyVendor\MyExtension\ViewHelpers;

-use TYPO3Fluid\Fluid\Core\Rendering\RenderingContextInterface;
 use TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper;
-use TYPO3Fluid\Fluid\Core\ViewHelper\Traits\CompileWithContentArgumentAndRenderStatic;

 final class GravatarViewHelper extends AbstractViewHelper
 {
-    use CompileWithContentArgumentAndRenderStatic;
-
     protected $escapeOutput = false;

     public function initializeArguments(): void
     {
         $this->registerArgument('emailAddress', 'string', 'The email address to resolve the gravatar for');
     }

-    public static function renderStatic(array $arguments, \Closure $renderChildrenClosure, RenderingContextInterface $renderingContext): string {
+    public function render(): string {
-        $emailAddress = $renderChildrenClosure();
+        $emailAddress = $this->renderChildren();

         return sprintf('<img src="https://www.gravatar.com/avatar/%s" />', md5($emailAddress));
     }

     public function getContentArgumentName(): string
     {
         return 'emailAddress';
     }
 }

line 13

Remove the trait \CompileWithContentArgumentAndRender .

lines 22, 23

Switch the render method from renderStatic() to render().

lines 24, 25

Use the non-static method $this->renderChildren() instead of the closure $renderChildrenClosure().

Remove calls to removed renderStatic() method of another ViewHelper

If you called a now removed renderStatic() method from within another ViewHelper's renderStatic() method you can replace the code like this:

 <?php

 declare(strict_types=1);

 namespace MyVendor\MyExtension\ViewHelpers;

-use TYPO3Fluid\Fluid\Core\Rendering\RenderingContextInterface;
 use TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper;
-use TYPO3Fluid\Fluid\Core\ViewHelper\Traits\CompileWithRenderStatic;

 final class GravatarViewHelper extends AbstractViewHelper
 {
-    use CompileWithRenderStatic;
-
     protected $escapeOutput = false;

     public function initializeArguments(): void
     {
         $this->registerArgument('emailAddress', 'string', 'The email address to resolve the gravatar for', true);
     }

-    public static function renderStatic(array $arguments, \Closure $renderChildrenClosure, RenderingContextInterface $renderingContext): string
+    public function render(): string
     {
-        $emailAddress = $arguments['emailAddress'];
+        $emailAddress = $this->arguments['emailAddress'];
-        $gravatorUrl = GravatarUrlViewHelper::renderStatic(['email', $emailAddress], $renderChildrenClosure, $renderingContext);
+        $gravatarUrl = $this->renderingContext->getViewHelperInvoker()->invoke(
+            GravatarUrlViewHelper::class,
+            ['email', $emailAddress],
+            $this->renderingContext,
+            $this->renderChildren(),
+        );

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

line 27, 28ff

Replace the static call to the renderStatic() method of another ViewHelper by calling $this->renderingContext->getViewHelperInvoker()->invoke() instead.

See also \TYPO3Fluid\Fluid\Core\ViewHelper\ViewHelperInvoker .