Create a custom `Helper`¶

Any Helper implemented in the frontend via JavaScript and used in Handlebars templates must also be replicated in PHP. For this purpose, the extension provides an interface Fr\Typo3Handlebars\Renderer\Helper\HelperInterface.

Note

In the following examples, a Helper is created with the identifier greet. The associated class name is Vendor\Extension\Renderer\Helper\GreetHelper.

Implementation options¶

There are several ways to implement Helpers. To understand how Helpers are resolved in the Renderer, it is worth taking a look at the responsible Trait.

Basically every registered Helper must be callable. This means that both globally defined functions and invokable classes as well as class methods are possible. See what options are available in the following examples.

Global function¶

Any globally registered function can be used as a Helper, provided that it is recognized by the registered PHP autoloader.

function greet(array $context): string
{
    return sprintf('Hello, %s!', $context['hash']['name']);
}

Invokable class¶

Invokable classes can also be used as Helpers. For this it is necessary that they implement the method __invoke().

# Classes/Renderer/Helper/GreetHelper.php

namespace Vendor\Extension\Renderer\Helper;

use Fr\Typo3Handlebars\Renderer\Helper\HelperInterface;

class GreetHelper implements HelperInterface
{
    public function __invoke(array $context): string
    {
        return sprintf('Hello, %s!', $context['hash']['name']);
    }
}

Class method (recommended)¶

The most convenient variant is the implementation of a class and an associated method. This also allows, for example, the use of dependency injection, provided that a corresponding registration of the Helper takes place via the service container.

# Classes/Renderer/Helper/GreetHelper.php

namespace Vendor\Extension\Renderer\Helper;

use Fr\Typo3Handlebars\Renderer\Helper\HelperInterface;
use Vendor\Extension\Domain\Repository\PersonRepository;

class GreetHelper implements HelperInterface
{
    private PersonRepository $repository;

    public function __construct(PersonRepository $repository)
    {
        $this->repository = $repository;
    }

    public function greetById(array $context): string
    {
        $name = (int)$this->getNameById($context['hash']['userId']);

        return sprintf('Hello, %s!', $name);
    }

    private function getNameById(int $userId): string
    {
        return $this->repository->findByUid($userId)->getName();
    }
}

Registration¶

Helpers can be registered either via configuration in the Services.yaml file or directly via the Renderer (if the default Renderer is used).

Automatic registration via the service container (recommended)¶

The recommended way to register Helpers is to use the global service container. This ensures that the Helpers are always available in the Renderer. To achieve this, add the following lines to your Services.yaml file:

# Configuration/Services.yaml

services:
  Vendor\Extension\Renderer\Helper\GreetHelper:
    tags:
      - name: handlebars.helper
        identifier: 'greet'
        method: 'greetById'

Warning

Only for implementation as class method

Note that registration using a tag is available only for the implementation as Class method (recommended). For all other implementations, a direct method call must currently still be registered:

# Configuration/Services.yaml

services:
  handlebars.renderer_extended:
    parent: handlebars.renderer
    calls:
      # Global function
      - registerHelper: ['greet', 'greet']
      # or invokable class
      - registerHelper: ['greet', '@Vendor\Extension\Renderer\Helper\GreetHelper']

  Fr\Typo3Handlebars\Renderer\RendererInterface:
    alias: 'handlebars.renderer_extended'

The identifier configuration specifies how the Helper should be named and referenced. It will then be used in Handlebars templates when calling the registered Helper. An example template could look like this:

{{ greet id=1 }}

It will result in: Hello, Bob!

method defines the class method to be used as a callback in combination with the configured class name. The above example leads to the registration of a new Helper named greet which provides a callback Vendor\Extension\Renderer\Helper\GreetHelper::greetById.

Manual registration¶

In addition to automatic registration, Helpers can also be registered manually at any time. For this purpose it is necessary to initialize the Renderer beforehand. Then a Helper can be registered with the registerHelper() method and thus made available in the Renderer:

$renderer->registerHelper(
    'greet',
    \Vendor\Extension\Renderer\Helper\GreetHelper::class . '::greetById'
);

Create a custom Helper¶