What does it do? 

The extension provides a full rendering environment for Handlebars templates within TYPO3 CMS. All core features of Handlebars.js are supported by the usage of the third-party library PHP Handlebars.

Its main use is to seamlessly integrate Handlebars templates into TYPO3 without the need to modify these templates again for output in TYPO3.

Features 

• Templating engine: Full Handlebars rendering environment for TYPO3
• Custom Helpers: Custom helpers with auto-registration via PHP attributes
• Extbase support: Controller-based rendering via HandlebarsView
• Events: PSR-14 hooks into the full rendering pipeline
• DI integration: Built on dependency injection for better performance and maintainability
• Caching: Integration with TYPO3's cache framework for compiled templates
• Extensibility: Easy to extend and customize
• Compatibility: Compatible with TYPO3 13.4 LTS and 14.3 LTS

Support 

There are several ways to get support for this extension:

• Slack: https://typo3.slack.com/messages/ext-handlebars
• GitHub: https://github.com/CPS-IT/handlebars/issues

License 

This extension is licensed under GNU General Public License 2.0 (or later).

Requirements 

• PHP 8.2 - 8.5
• TYPO3 13.4 LTS - 14.3 LTS

Installation 

Require the extension via Composer (recommended):

composer require cpsit/typo3-handlebars

Or download it from the TYPO3 extension repository.

Site sets 

The extension provides two site sets that can be included in the site configuration or any other site set.

• cpsit/handlebars — Handlebars base

  • Wires plugin.tx_handlebars.view.templateRootPaths and plugin.tx_handlebars.view.partialRootPaths from the site settings handlebars.view.templateRootPath and handlebars.view.partialRootPath.
  • Include this set for every site that renders Handlebars templates.

• cpsit/handlebars-content-element — Handlebars content elements

  • Sets lib.contentElement = HANDLEBARSTEMPLATE, replacing the default Fluid base object used by EXT:fluid_styled_content.
  • Include this set when all content elements should use Handlebars rendering by default.

dependencies:
  - cpsit/handlebars
  - cpsit/handlebars-content-element

Priority order 

tt_content.textmedia = HANDLEBARSTEMPLATE
tt_content.textmedia {
    templateRootPaths {
        10 = EXT:my_extension/Resources/Private/Templates
    }
    partialRootPaths {
        10 = EXT:my_extension/Resources/Private/Partials
    }
}

plugin.tx_handlebars {
    view {
        templateRootPaths {
            10 = EXT:my_extension/Resources/Private/Templates
        }
        partialRootPaths {
            10 = EXT:my_extension/Resources/Private/Partials
        }
    }
}

handlebars:
  view:
    templateRootPaths:
      10: EXT:my_extension/Resources/Private/Templates
    partialRootPaths:
      10: EXT:my_extension/Resources/Private/Partials

Template name resolution 

Once the root paths are collected, the active TemplateResolver turns a template or partial name into an absolute file path. The default resolver supports two addressing styles: directory-relative paths and flat @-prefixed names.

tt_content.tx_myext_teaser = HANDLEBARSTEMPLATE
tt_content.tx_myext_teaser {
    templateName = @teaser
}

{{> @card}}

{{> @card--highlighted}}   {{!-- falls back to @card if not found --}}

Global variables 

Global variables are merged into every template rendering automatically. They can be defined through TypoScript or the service container.

plugin.tx_handlebars {
    variables {
        publicPath = /assets
        siteName = My Site
    }
}

handlebars:
  variables:
    publicPath: /assets
    apiEndpoint: https://api.example.com

Per-rendering variables 

Variables scoped to a single rendering are declared in the variables property of a HANDLEBARSTEMPLATE content object. Each entry is processed as a standard content object against the current record's data:

tt_content.header = HANDLEBARSTEMPLATE
tt_content.header {
    templateName = Header

    variables {
        header = TEXT
        header.field = header

        subheader = TEXT
        subheader.field = subheader

        link = TEXT
        link.typolink.parameter.field = header_link
    }
}

Entries with no sub-configuration are treated as simple variables and passed to the template as-is, without invoking ContentObjectRenderer:

variables {
    # Content object — field value is rendered via cObjGetSingle
    header = TEXT
    header.field = header

    # Simple variables — values are passed through directly
    cssClass = my-element
    theme = dark
}

Two variables are always injected automatically and cannot be overridden (this reflects the same behavior as in FLUIDTEMPLATE):

data

The full data array of the current content element record.

current

The value of the current field ( $cObj->currentValKey).

rendering.strictMode 

Type

boolean

Default

false

Description

Enables strict mode for the Handlebars renderer. In strict mode, the compiled template throws an exception as soon as it encounters a variable, property, or path that does not exist, instead of silently rendering an empty string. This is useful during development to catch typos in variable names and template paths early.

Next steps 

• HANDLEBARSTEMPLATE content object — complete reference for all HANDLEBARSTEMPLATE properties
• Data processors — enrich templates with database queries, menus, and custom variable processing
• Custom helpers — expose custom PHP logic to templates

templateName 

Type

string / stdWrap

Description

Name of the template to render. The value is resolved as a filename (without the .hbs extension) relative to the configured template root paths. Exactly one of templateName, template, or file must be set.

Example

templateName = Header

# With stdWrap
templateName.field = tx_myext_template_name

Copied!

template 

Type

string / stdWrap

Description

Inline Handlebars source used directly as the template. Useful for short or dynamically constructed templates. Cannot be used together with templateName or file.

Example

template = <h1>{{header}}</h1>

Copied!

file 

Type

string / stdWrap

Description

Absolute or EXT:-relative path to a Handlebars template file. Cannot be used together with templateName or template.

Example

file = EXT:my_extension/Resources/Private/Templates/Special.hbs

Copied!

templateRootPaths 

Type

array (numeric keys)

Description

Template root paths for this content object. These are added to the content object path provider with the highest priority (100), overriding any TypoScript or service container paths for this rendering. Higher numeric keys take precedence over lower ones.

Example

templateRootPaths {
    10 = EXT:my_extension/Resources/Private/Templates
    20 = EXT:my_other_extension/Resources/Private/Templates
}

Copied!

partialRootPaths 

Type

array (numeric keys)

Description

Partial root paths for this content object. Same priority and override rules as templateRootPaths.

Example

partialRootPaths {
    10 = EXT:my_extension/Resources/Private/Partials
}

Copied!

variables 

Type

array

Description

Variables passed to the template. Each entry is processed as a content object against the current content element's data record. Simple string values are passed through as-is; entries with a sub-array are rendered via ContentObjectRenderer::cObjGetSingle().

Two variable names are reserved and always available automatically:

• data — the full content element data array
• current — the current field value

Example

variables {
    header = TEXT
    header.field = header

    bodytext = TEXT
    bodytext.field = bodytext
    bodytext.parseFunc < lib.parseFunc_RTE

    image = FILES
    image.references.fieldName = image
}

Copied!

settings 

Type

array

Description

Arbitrary key-value pairs passed to the template as the settings variable. Unlike variables, entries are not processed as content objects — values are used as plain strings.

Example

settings {
    showDate = 1
    dateFormat = d.m.Y
}

Copied!

In the template:

{{#if settings.showDate}}
    <time>{{formatDate date settings.dateFormat}}</time>
{{/if}}

Copied!

dataProcessing 

Type

array

Description

Standard data processors, executed after variables are resolved. Processors receive and return the $processedData array. Any key added by a processor is available as a template variable.

The extension provides three additional processors: process-variables, resolve-markers, and unflatten-variable-names.

Example

dataProcessing {
    10 = database-query
    10 {
        table = tx_myext_domain_model_item
        as = items
    }

    20 = process-variables
    20 {
        as = items
        merge = 1
        variables {
            label = TEXT
            label.field = title
        }
    }
}

Copied!

preProcessing 

Type

array

Description

Data source aware processors executed before variables are processed. These can read from multiple data sources (content element record, processed data, processor configuration) and modify the variable set before content object rendering begins.

postProcessing 

Type

array

Description

Data source aware processors executed after variables have been resolved and data processors have run, but before the template is rendered.

assets 

Type

array

Description

Registers JavaScript and CSS assets via TYPO3's AssetCollector API. Supports four sub-keys: javaScript, inlineJavaScript, css, inlineCss.

Example

assets {
    javaScript {
        my-ext-app {
            source = EXT:my_extension/Resources/Public/JavaScript/app.js
            attributes.defer = 1
            options.useNonce = 1
        }
    }
    css {
        my-ext-styles {
            source = EXT:my_extension/Resources/Public/Css/styles.css
        }
    }
}

Copied!

headerAssets 

Type

content object

Description

Adds arbitrary markup to the page <head>. The value is evaluated as a content object and the result is passed to PageRenderer::addHeaderData().

Example

headerAssets = TEXT
headerAssets.value = <link rel="stylesheet" href="/assets/styles.css">

Copied!

footerAssets 

Type

content object

Description

Adds arbitrary markup before the closing </body> tag. The value is evaluated as a content object and the result is passed to PageRenderer::addFooterData().

Example

footerAssets = TEXT
footerAssets.value = <script src="/assets/app.js"></script>

Copied!

stdWrap 

Type

stdWrap

Description

Standard TYPO3 stdWrap processing applied to the final rendered output.

Example

stdWrap.wrap = <div class="handlebars-content">|</div>

Copied!

TypoScript configuration 

Per-plugin Handlebars configuration lives under the handlebars key in the plugin's TypoScript configuration:

plugin.tx_myextension_myplugin {
    handlebars {
        default {
            templateRootPaths.10 = EXT:my_extension/Resources/Private/Templates/Handlebars
            partialRootPaths.10 = EXT:my_extension/Resources/Private/Partials/Handlebars
        }
    }
}

plugin.tx_myextension_myplugin {
    handlebars {
        default {
            templateRootPaths.10 = EXT:my_extension/Resources/Private/Templates/Handlebars
            partialRootPaths.10 = EXT:my_extension/Resources/Private/Partials/Handlebars
        }
        Blog {
            templateRootPaths.20 = EXT:my_extension/Resources/Private/Templates/Blog
        }
        Blog::list {
            templateName = @blog-list
        }
    }
}

Default template name 

When no templateName is configured, the factory derives one automatically from the controller alias and action name:

<ControllerAlias>/<actionName>

For BlogController::listAction() with alias Blog this resolves to Blog/list.hbs under the configured template root paths.

HandlebarsController 

For controllers you own, extend \CPSIT\Typo3Handlebars\Controller\HandlebarsController instead of ActionController. This guarantees Handlebars rendering even when no handlebars TypoScript key is present — the factory always returns a HandlebarsView for these controllers:

namespace Vendor\MyExtension\Controller;

use CPSIT\Typo3Handlebars\Controller\HandlebarsController;
use Psr\Http\Message\ResponseInterface;

final class BlogController extends HandlebarsController
{
    public function listAction(): ResponseInterface
    {
        $this->view->assign('posts', $this->postRepository->findAll());

        return $this->htmlResponse($this->renderView());
    }
}

Fluid fallback 

During an incremental migration you may need to keep some actions on Fluid while others are already on Handlebars. Call delegateRendering() on the view to hand off to the underlying Fluid view for that action:

public function legacyAction(): ResponseInterface
{
    $this->view->assign('items', $this->repository->findAll());

    $content = $this->view instanceof HandlebarsView
        ? $this->view->delegateRendering()
        : $this->view->render();

    return $this->htmlResponse((string)$content);
}

process-variables 

Class: \CPSIT\Typo3Handlebars\DataProcessing\ProcessVariablesProcessor

Processes a variables configuration block — exactly like the top-level variables of HANDLEBARSTEMPLATE — within a data processor chain. This is most useful when combined with other processors such as database-query, allowing per-record variable processing.

tt_content.my_element = HANDLEBARSTEMPLATE
tt_content.my_element {
    templateName = MyElement

    dataProcessing {
        10 = process-variables
        10 {
            variables {
                header = TEXT
                header.field = header

                teaser = TEXT
                teaser.field = bodytext
                teaser.parseFunc < lib.parseFunc_RTE
            }
        }
    }
}

dataProcessing {
    10 = database-query
    10 {
        table = tx_myext_domain_model_item
        as = items

        dataProcessing {
            10 = process-variables
            10 {
                table = tx_myext_domain_model_item
                as = item
                variables {
                    title = TEXT
                    title.field = title

                    body = TEXT
                    body.field = bodytext
                    body.parseFunc < lib.parseFunc_RTE
                }
            }
        }
    }
}

resolve-markers 

Class: \CPSIT\Typo3Handlebars\DataProcessing\ResolveMarkersProcessor

Replaces marker-style keys (e.g., ###NAV_ITEMS###) in the processed data with the values stored under those keys. The typical pattern is to use a marker as a named placeholder early in the chain — either as the as target of a preceding processor or directly in a variables entry — and then resolve all markers to clean variable names in a final step. This keeps intermediate processors decoupled from the variable names the template expects.

tt_content.my_element = HANDLEBARSTEMPLATE
tt_content.my_element {
    templateName = MyElement

    dataProcessing {
        # Declare the expected output slots early using markers — these
        # names will become the final template variables
        10 = menu
        10 {
            as = ###mainNavigation###
            levels = 2
        }

        20 = menu
        20 {
            as = ###footerLinks###
            special = directory
            special.value = 42
        }

        # Resolve all markers to clean variable names in one final step
        90 = resolve-markers
        90.removeNonMatchingMarkers = 1
    }
}

After processing, the template receives mainNavigation and footerLinks as clean variable names. The markers at the top of the chain serve as upfront documentation of what the template expects, while the processors that follow fill those slots independently.

unflatten-variable-names 

Class: \CPSIT\Typo3Handlebars\DataProcessing\UnflattenVariableNamesProcessor

Converts dot-separated flat variable names into nested arrays. This is useful when other processors set their as key to a dotted path, representing the intended position in a nested data structure.

dataProcessing {
    10 = menu
    10 {
        as = page.nav.mainMenu
    }

    20 = menu
    20 {
        as = page.nav.footerLinks
        special = directory
        special.value = 42
    }

    90 = unflatten-variable-names
}

After processing, the template receives a nested page object:

{{#each page.nav.mainMenu}}
    <a href="{{link}}">{{title}}</a>
{{/each}}

The processor has no configuration properties and operates on the entire processed data array.

Implement a helper 

Implement the \CPSIT\Typo3Handlebars\Renderer\Helper\Helper interface and place the #[AsHelper] attribute on the class. Because the class implements the Helper interface, the attribute automatically resolves to the render method:

namespace Vendor\Extension\Renderer\Helper;

use CPSIT\Typo3Handlebars\Attribute\AsHelper;
use CPSIT\Typo3Handlebars\Renderer\Helper\Helper;
use DevTheorem\Handlebars\HelperOptions;

#[AsHelper('greet')]
final readonly class GreetHelper implements Helper
{
    public function render(HelperOptions $options): mixed
    {
        return sprintf('Hello, %s!', $options->hash['name'] ?? 'World');
    }
}

The attribute can also be placed directly on a method, in which case the method name is inferred automatically — no method parameter needed. Dependency injection works normally for all #[AsHelper]-annotated classes:

use CPSIT\Typo3Handlebars\Attribute\AsHelper;
use CPSIT\Typo3Handlebars\Renderer\Helper\Helper;
use DevTheorem\Handlebars\HelperOptions;
use Vendor\Extension\Domain\Model\Person;
use Vendor\Extension\Domain\Repository\PersonRepository;

#[AsHelper('greet')]
final readonly class GreetHelper implements Helper
{
    public function __construct(
        private PersonRepository $repository,
    ) {}

    public function render(HelperOptions $options): mixed
    {
        return sprintf('Hello, %s!', $options->hash['name'] ?? 'World');
    }

    #[AsHelper('greetAll')]
    public function greetAll(HelperOptions $options): mixed
    {
        return implode(PHP_EOL, array_map(
            static fn(Person $person) => sprintf('Hello, %s!', $person->getName()),
            $this->repository->findAll(),
        ));
    }
}

use CPSIT\Typo3Handlebars\Attribute\AsHelper;
use DevTheorem\Handlebars\HelperOptions;

#[AsHelper('greet')]
final readonly class GreetHelper
{
    public function __invoke(HelperOptions $options): mixed
    {
        return sprintf('Hello, %s!', $options->hash['name'] ?? 'World');
    }
}

Use the helper in a template 

Reference the helper by its identifier:

{{greet name="Alice"}}

{{greetAll}}

Alternative: Register via Services.yaml 

If you cannot use the attribute (e.g., for a third-party class), register the helper explicitly in Services.yaml. Both identifier and method are required:

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

BeforeTemplateCompilationEvent 

Dispatched immediately before a template is compiled. The event provides read-only access to the rendering context and the renderer. Use it to inspect the context (e.g., to log which template is about to be rendered) or to trigger additional rendering via the renderer:

namespace Vendor\Extension\EventListener;

use CPSIT\Typo3Handlebars\Event\BeforeTemplateCompilationEvent;

final readonly class BeforeTemplateCompilationListener
{
    public function __invoke(BeforeTemplateCompilationEvent $event): void
    {
        $context = $event->getContext();   // RenderingContext
        $renderer = $event->getRenderer(); // Renderer
    }
}

BeforeRenderingEvent 

Dispatched after variables have been resolved and merged, immediately before the compiled template is executed. The full variable set can be read and modified:

namespace Vendor\Extension\EventListener;

use CPSIT\Typo3Handlebars\Event\BeforeRenderingEvent;

final readonly class BeforeRenderingListener
{
    public function __invoke(BeforeRenderingEvent $event): void
    {
        // Add a variable
        $event->addVariable('timestamp', time());

        // Replace the entire variable set
        $variables = $event->getVariables();
        $variables['title'] = strtoupper($variables['title'] ?? '');
        $event->setVariables($variables);

        // Remove a variable
        $event->removeVariable('internalFlag');
    }
}

Available methods:

• getVariables() / setVariables(array $variables) — get or replace the full variable set
• addVariable(string $name, mixed $value) — add or overwrite a single variable
• removeVariable(string $name) — remove a variable by name
• getContext() — the RenderingContext (read-only)
• getRenderer() — the Renderer (read-only)

AfterRenderingEvent 

Dispatched after the template has been fully rendered. The rendered HTML string can be read and replaced:

namespace Vendor\Extension\EventListener;

use CPSIT\Typo3Handlebars\Event\AfterRenderingEvent;

final readonly class AfterRenderingListener
{
    public function __invoke(AfterRenderingEvent $event): void
    {
        $content = $event->getContent();
        $event->setContent(trim($content));
    }
}

Available methods:

• getContent() / setContent(string $content) — get or replace the rendered output
• getContext() — the RenderingContext (read-only)
• getRenderer() — the Renderer (read-only)

Asset Types 

The AssetCollector API supports four distinct asset types, all fully supported by this extension:

1. External JavaScript files — link to external .js files
2. Inline JavaScript code — embed JavaScript directly in the page
3. External CSS files — link to external .css files
4. Inline CSS code — embed styles directly in the page

10 = HANDLEBARSTEMPLATE
10 {
    templateName = MyTemplate

    assets {
        javaScript {
            my-app-script {
                source = EXT:myext/Resources/Public/JavaScript/app.js
                attributes {
                    async = 1
                    defer = 1
                    crossorigin = anonymous
                }
                options {
                    priority = 1
                    csp = 1
                }
            }
        }
    }
}

assets {
    inlineJavaScript {
        my-inline-script {
            source = console.log('Hello from Handlebars'); initMyApp();
            attributes {
                type = module
            }
            options {
                priority = 1
            }
        }
    }
}

assets {
    css {
        my-styles {
            source = EXT:myext/Resources/Public/Css/styles.css
            attributes {
                media = screen and (max-width: 768px)
            }
            options {
                priority = 1
            }
        }
    }
}

assets {
    inlineCss {
        critical-css {
            source = body { margin: 0; padding: 0; } .container { max-width: 1200px; }
        }
    }
}

Configuration reference 

Wiring the implementation 

Register the custom renderer as the implementation of the Renderer interface in your extension's Services.yaml:

services:
  CPSIT\Typo3Handlebars\Renderer\Renderer:
    alias: Vendor\Extension\Renderer\MyRenderer

FlatTemplateResolver 

FlatTemplateResolver is the default implementation. It scans all configured root paths recursively and builds an in-memory map of every template file, keyed by its bare filename (without directory). A lookup therefore succeeds regardless of where in the directory tree the file lives.

Template and partial names must be prefixed with @ to trigger flat resolution. A name without the prefix is passed directly to HandlebarsTemplateResolver (see below).

tt_content.tx_myext_teaser = HANDLEBARSTEMPLATE
tt_content.tx_myext_teaser {
    templateName = @teaser
}

{{> @card}}

Variant separator

Appending --<variant> to an @-prefixed name selects a variant of a component. If no file with that exact name exists, the resolver automatically falls back to the base name:

{{> @card--highlighted}}   {{!-- falls back to @card if not found --}}

This convention follows Fractal's naming rules.

File precedence

When the same filename exists under multiple root paths, the higher-priority root path wins (see Template paths). Within a single root path, files are sorted by name and the first occurrence is used, matching Fractal's uniqueness guarantee.

HandlebarsTemplateResolver 

HandlebarsTemplateResolver resolves template and partial names as paths relative to the configured root paths. Given the name Blog/List, it searches each root path (highest priority first) for a matching file — for example Blog/List.hbs.

This resolver is used as the fallback inside FlatTemplateResolver for any name that does not start with @, so both resolution strategies are active at the same time.

Example implementation 

namespace Vendor\Extension\Renderer\Template;

use CPSIT\Typo3Handlebars\Exception;
use CPSIT\Typo3Handlebars\Renderer\Template\BaseTemplateResolver;
use CPSIT\Typo3Handlebars\Renderer\Template\TemplatePaths;

final readonly class MyTemplateResolver extends BaseTemplateResolver
{
    public function __construct(
        private TemplatePaths $templatePaths,
    ) {}

    public function resolveTemplatePath(string $templatePath, ?string $format = null): string
    {
        [$templateRootPaths] = $this->resolveTemplatePaths($this->templatePaths);

        foreach (array_reverse($templateRootPaths) as $rootPath) {
            $filename = $this->resolveFilename($templatePath, $rootPath, $format ?? 'hbs');

            if (is_file($filename)) {
                return $filename;
            }
        }

        throw new Exception\TemplatePathIsNotResolvable($templatePath);
    }

    public function resolvePartialPath(string $partialPath, ?string $format = null): string
    {
        [, $partialRootPaths] = $this->resolveTemplatePaths($this->templatePaths);

        foreach (array_reverse($partialRootPaths) as $rootPath) {
            $filename = $this->resolveFilename($partialPath, $rootPath, $format ?? 'hbs');

            if (is_file($filename)) {
                return $filename;
            }
        }

        throw new Exception\PartialPathIsNotResolvable($partialPath);
    }
}

Wiring the implementation 

Register the custom resolver as the implementation of the TemplateResolver interface in your extension's Services.yaml:

services:
  CPSIT\Typo3Handlebars\Renderer\Template\TemplateResolver:
    alias: Vendor\Extension\Renderer\Template\MyTemplateResolver

Reading from DataSourceCollection 

DataSourceCollection::resolve() searches the data sources in priority order and returns the first match. Pass a specific DataSource case to restrict the lookup:

use CPSIT\Typo3Handlebars\DataProcessing\DataSource\DataSource;

// Search all sources (highest priority first)
$table = $collection->resolve('table');

// Search only the processor configuration
$table = $collection->resolve('table', DataSource::ProcessorConfiguration);

// Search two specific sources, in the given order
$table = $collection->resolve('table', [
    DataSource::ProcessorConfiguration,
    DataSource::ContentObjectConfiguration,
]);

The four DataSource cases are:

• DataSource::ProcessorConfiguration — this processor's own config block
• DataSource::ProcessedData — accumulated output from previous processors
• DataSource::ContentObjectRenderer — current record's field values
• DataSource::ContentObjectConfiguration — top-level HANDLEBARSTEMPLATE config

Example implementation 

namespace Vendor\Extension\DataProcessing;

use CPSIT\Typo3Handlebars\DataProcessing\DataSource\DataSource;
use CPSIT\Typo3Handlebars\DataProcessing\DataSource\DataSourceAwareProcessor;
use CPSIT\Typo3Handlebars\DataProcessing\DataSource\DataSourceCollection;
use TYPO3\CMS\Frontend\ContentObject\ContentObjectRenderer;

final readonly class MyPreProcessor implements DataSourceAwareProcessor
{
    public function process(
        array $variables,
        DataSourceCollection $collection,
        ContentObjectRenderer $contentObjectRenderer,
    ): array {
        $table = $collection->resolve('table', DataSource::ProcessorConfiguration, 'tt_content');
        $variables['tableName'] = $table;

        return $variables;
    }
}

Registering the processor 

Reference the processor class by its fully qualified class name in preProcessing or postProcessing:

10 = process-variables
10 {
    variables {
        header = TEXT
        header.field = header
    }

    preProcessing {
        10 = Vendor\Extension\DataProcessing\MyPreProcessor
    }
}

The numeric keys control execution order when multiple processors are registered. The class is instantiated via GeneralUtility::makeInstance(), so constructor injection works as normal.

PathProvider 

Implement the \CPSIT\Typo3Handlebars\Renderer\Template\Path\PathProvider interface to contribute template and partial root paths programmatically — for example when paths depend on the current site configuration or a value not available at container compile time.

Higher priority values are merged last and therefore take precedence over lower ones. The three built-in providers use 0 ( GlobalPathProvider), 50 ( TypoScriptPathProvider), and 100 ( ContentObjectPathProvider).

interface PathProvider

Fully qualified name

\CPSIT\Typo3Handlebars\Renderer\Template\Path\PathProvider

getTemplateRootPaths ( )

Return an array of template root paths, keyed by integer priority.

returntype

array

getPartialRootPaths ( )

Return an array of partial root paths, keyed by integer priority.

returntype

array

isCacheable ( )

Return true if the paths provided by this provider may be cached. Return false for request-dependent paths.

returntype

bool

getPriority ( )

Return the priority of this provider. Higher values win.

returntype

int

namespace Vendor\Extension\Renderer\Template\Path;

use CPSIT\Typo3Handlebars\Renderer\Template\Path\PathProvider;
use TYPO3\CMS\Core\Site\SiteFinder;

final readonly class SitePathProvider implements PathProvider
{
    public function __construct(
        private SiteFinder $siteFinder,
    ) {}

    public function getTemplateRootPaths(): array
    {
        return [];
    }

    public function getPartialRootPaths(): array
    {
        return [];
    }

    public function isCacheable(): bool
    {
        return false;
    }

    public static function getPriority(): int
    {
        return 25;
    }
}

The class is picked up automatically because PathProvider carries #[AutoconfigureTag('handlebars.template_path_provider')]. No extra Services.yaml entry is needed beyond standard autowiring.

VariableProvider 

Implement the \CPSIT\Typo3Handlebars\Renderer\Variables\VariableProvider interface to inject variables into every template rendering without repeating them in TypoScript. Common uses include a site-wide locale string, feature flags, or shared navigation data.

Providers are merged in ascending priority order; a higher-priority provider can overwrite keys from a lower-priority one. The built-in GlobalVariableProvider uses priority 0.

interface VariableProvider

Fully qualified name

\CPSIT\Typo3Handlebars\Renderer\Variables\VariableProvider

get ( )

Return the variables contributed by this provider.

returntype

array

getPriority ( )

Return the priority of this provider. Higher values win.

returntype

int

namespace Vendor\Extension\Renderer\Variables;

use CPSIT\Typo3Handlebars\Renderer\Variables\VariableProvider;
use TYPO3\CMS\Core\Site\SiteFinder;

final readonly class SiteVariableProvider implements VariableProvider
{
    public function __construct(
        private SiteFinder $siteFinder,
    ) {}

    public function get(): array
    {
        return [
            'siteName' => $this->siteFinder->getSiteByPageId(0)->getIdentifier(),
        ];
    }

    public function offsetExists(mixed $offset): bool
    {
        return array_key_exists($offset, $this->get());
    }

    public function offsetGet(mixed $offset): mixed
    {
        return $this->get()[$offset] ?? null;
    }

    public function offsetSet(mixed $offset, mixed $value): never
    {
        throw new \LogicException('Variables are read-only.', 1781693633);
    }

    public function offsetUnset(mixed $offset): never
    {
        throw new \LogicException('Variables are read-only.', 1781693639);
    }

    public static function getPriority(): int
    {
        return 10;
    }
}

Like PathProvider, the class is picked up automatically via #[AutoconfigureTag('handlebars.variable_provider')] on the interface.

The logic-less philosophy 

Fluid templates can contain complex expressions: inline ViewHelper chaining, boolean operators, type-coercing comparisons, and dynamic dispatch to arbitrary PHP classes. This power comes at the cost of templates that are hard to read outside of a PHP context.

Handlebars is explicitly "logic-less". Templates may only output values, iterate over arrays, and branch on truthiness. All other logic must live in a named helper — a PHP callable registered with the renderer. This constraint keeps templates readable by designers and front-end developers who do not know PHP, and it shifts complexity to a layer that can be unit-tested cleanly.

Concept-by-concept mapping 

The table below maps every major Fluid concept to its Handlebars equivalent. Detailed examples for each row are given in the linked pages.

Things Handlebars does not have 

Some Fluid features have no direct equivalent and require a different approach:

Inline ViewHelper chains

Fluid allows {value -> f:format.trim() -> f:format.upper()}. In Handlebars, compose the same logic in a single helper that applies both transformations.

Arithmetic and boolean operators in templates

Fluid supports {a + b} and {a && b} in some contexts. In Handlebars, compute the result in a data processor or a helper and expose it as a plain variable.

Type-aware comparisons

<f:if condition="{count} > 0"> works in Fluid because it parses the expression. Handlebars {{#if count}} only tests truthiness — 0 and the empty string are falsy, everything else is truthy. Write a helper if you need a numeric comparison.

Named format strings in the template

Fluid's <f:format.*> ViewHelpers apply a PHP function to a value. Replace each one with a small helper whose name describes the transformation (e.g., {{formatDate date format="d.m.Y"}}).

Outputting a variable 

Handlebars HTML-escapes every {{...}} expression by default.

Fluid:

{header}

Handlebars:

{{header}}

Raw / unescaped output 

Use triple braces to output a value without HTML escaping. Reserve this for content that has already been sanitized (e.g., a parseFunc-processed RTE field).

Fluid:

{bodytext -> f:format.raw()}

Handlebars:

{{{bodytext}}}

Conditionals 

{{#if}} is truthy: empty strings, 0, empty arrays, and null are all falsy. For numeric comparisons, write a helper (see Helpers).

Fluid:

<f:if condition="{header}">
    <h1>{header}</h1>
</f:if>

<f:if condition="{showTeaser}">
    <f:then><p>{teaser}</p></f:then>
    <f:else><p>{fallback}</p></f:else>
</f:if>

Handlebars:

{{#if header}}
    <h1>{{header}}</h1>
{{/if}}

{{#if showTeaser}}
    <p>{{teaser}}</p>
{{else}}
    <p>{{fallback}}</p>
{{/if}}

Use {{#unless}} as shorthand for a negated {{#if}} without an else branch:

Fluid:

<f:if condition="{hideDate}">
    <f:else><time>…</time></f:else>
</f:if>

Handlebars:

{{#unless hideDate}}
    <time>…</time>
{{/unless}}

Loops 

Inside {{#each}}, {{this}} refers to the current item and @index holds the zero-based iteration counter. @first and @last are boolean flags for the boundary items.

Fluid:

<f:for each="{items}" as="item" iteration="loop">
    <li class="{f:if(condition: loop.isFirst, then: 'is-first')}">
        {item.title}
    </li>
</f:for>

Handlebars:

{{#each items}}
    <li{{#if @first}} class="is-first"{{/if}}>
        {{this.title}}
    </li>
{{/each}}

Nested {{#each}} blocks access the parent scope via ../:

{{#each categories}}
    <h2>{{this.title}}</h2>
    {{#each this.items}}
        <p>{{this.label}} (category: {{../title}})</p>
    {{/each}}
{{/each}}

Scoping with {{#with}} 

{{#with}} sets a new scope root, similar to assigning a sub-object and then using it directly. Inside the block, properties of the given object are accessible without a prefix.

Fluid (using a variable alias via f:alias):

<f:alias map="{addr: '{data.address}'}">
    {addr.street}, {addr.city}
</f:alias>

Handlebars:

{{#with data.address}}
    {{street}}, {{city}}
{{/with}}

Partials 

Handlebars partials are resolved relative to the configured partial root paths in the same way as templates. The partial name is the filename without the .hbs extension.

Fluid:

<f:render partial="Teaser" />

<f:render partial="Card" arguments="{title: item.title, image: item.image}" />

Handlebars:

{{> Teaser}}

{{> Card title=item.title image=item.image}}

To pass the entire current context to the partial (as Fluid does with the arguments="{_all}" attribute), just omit any arguments:

{{> Teaser}}

To pass a completely different context object, provide it as a positional argument before any hash arguments:

{{> Card item}}

Dynamic property access 

Handlebars dot-path notation resolves nested public properties: {{user.address.city}}. For getter resolution (using Extbase's ObjectAccess) and dynamic key lookups (where the key itself is a variable), use the built-in get helper:

Fluid:

{object.{dynamicKey}}
{object.privateProperty.arrayKey}

Handlebars:

{{get object dynamicKey}}
{{get object 'privateProperty[arrayKey]'}}

Comments 

Handlebars comments are stripped from the rendered output and never appear in the HTML source. Use them for template-internal notes.

Fluid:

<!-- this comment appears in HTML source -->

Handlebars:

{{!-- this comment is stripped from the output --}}

Escaping Handlebars delimiters 

To output a literal {{ in the rendered HTML, use the raw block syntax:

{{{raw}}}}
    This {{{will not be}}} parsed as Handlebars.
{{{{/raw}}}}

How the systems compare 

Fluid uses a push model: a child template declares which layout it inherits and then pushes named sections into the layout's named slots. Handlebars uses the same model, but the building blocks are ordinary helpers rather than dedicated language constructs.

The content helper supports an optional mode hash argument (replace / append / prepend) that controls how the child's content is merged with the layout block's default. replace is the default and matches Fluid's behaviour.

Side-by-side example 

Layout file — Fluid:

<!DOCTYPE html>
<html>
<head>
    <f:render section="Head" optional="true" />
</head>
<body>
    <header>
        <f:render section="Header" />
    </header>
    <main>
        <f:render section="Main" />
    </main>
    <footer>
        <f:render section="Footer" optional="true" />
    </footer>
</body>
</html>

Layout file — Handlebars:

<!DOCTYPE html>
<html>
<head>
    {{#block "head"}}{{/block}}
</head>
<body>
    <header>
        {{#block "header"}}{{/block}}
    </header>
    <main>
        {{#block "main"}}{{/block}}
    </main>
    <footer>
        {{#block "footer"}}{{/block}}
    </footer>
</body>
</html>

Child template — Fluid:

<f:layout name="Main" />

<f:section name="Head">
    <title>{header}</title>
</f:section>

<f:section name="Header">
    <h1>{header}</h1>
</f:section>

<f:section name="Main">
    <p>{bodytext}</p>
</f:section>

Child template — Handlebars:

{{#extend "Main"}}
    {{#content "head"}}
        <title>{{header}}</title>
    {{/content}}

    {{#content "header"}}
        <h1>{{header}}</h1>
    {{/content}}

    {{#content "main"}}
        <p>{{bodytext}}</p>
    {{/content}}
{{/extend}}

Default content in blocks 

A {{#block}} can hold default markup that is used verbatim when the child provides no matching {{#content}} for that slot. This is the equivalent of Fluid's optional="true" on <f:render section="..."> combined with a fallback in the layout.

<footer>
    {{#block "footer"}}
        <p>&copy; {{year}} My Site</p>
    {{/block}}
</footer>

A child template that does not declare a {{#content "footer"}} block will render the default copyright line automatically.

Appending and prepending content 

The mode argument lets a child add to a block rather than replace it. This has no direct Fluid equivalent and is often used for accumulating <script> or <link> tags:

{{#extend "Main"}}
    {{#content "head" mode="append"}}
        <link rel="stylesheet" href="/assets/my-element.css">
    {{/content}}

    {{#content "main"}}
        …
    {{/content}}
{{/extend}}

Using partials without a layout 

Not every template needs a full layout. Reusable snippets that were Fluid partials map directly to Handlebars partials with no extra ceremony — just create a .hbs file in the partial root path and include it with {{> Name}}.

ViewHelpers vs. Helpers 

A Fluid ViewHelper is a PHP class that implements \TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper . Arguments are declared via initializeArguments() and the class is resolved by its namespace prefix (e.g., f:, myext:).

A Handlebars helper is any PHP callable registered via the :php: #[AsHelper] attribute. Arguments reach the callable either as named hash arguments (name=value pairs after the helper name) or as positional arguments (bare values in order). There is no argument declaration step — the method signature is the contract.

Porting an inline ViewHelper 

Inline ViewHelpers that transform a single value (like <f:format.date>) are the most common case. The Handlebars equivalent is a helper that receives the value as a positional argument and returns the formatted string.

Fluid:

<f:format.date format="d.m.Y">{date}</f:format.date>

{date -> f:format.date(format: 'd.m.Y')}

Handlebars:

{{formatDate date format="d.m.Y"}}

Helper implementation:

namespace Vendor\Extension\Renderer\Helper;

use CPSIT\Typo3Handlebars\Attribute\AsHelper;
use DevTheorem\Handlebars\HelperOptions;

#[AsHelper('formatDate')]
final readonly class FormatDateHelper
{
    public function __invoke(HelperOptions $options, ?\DateTimeInterface $date = null): ?string
    {
        $format = is_string($options->hash['format'] ?? null)
            ? $options->hash['format']
            : 'd.m.Y';

        return $date?->format($format);
    }
}

Porting a block / wrapping ViewHelper 

ViewHelpers that wrap inner content (block ViewHelpers) correspond to Handlebars block helpers. The inner content is rendered via $options->fn($options->scope) and the inverse ({{else}}) branch via $options->inverse($options->scope).

Fluid:

<myext:ifGranted role="ADMIN">
    <a href="/admin">Admin panel</a>
</myext:ifGranted>

Handlebars:

{{#ifGranted role="ADMIN"}}
    <a href="/admin">Admin panel</a>
{{/ifGranted}}

Helper implementation:

namespace Vendor\Extension\Renderer\Helper;

use CPSIT\Typo3Handlebars\Attribute\AsHelper;
use DevTheorem\Handlebars\HelperOptions;
use Vendor\Extension\Security\AccessChecker;

#[AsHelper('ifGranted')]
final readonly class IfGrantedHelper
{
    public function __construct(
        private AccessChecker $accessChecker,
    ) {}

    public function __invoke(HelperOptions $options): string
    {
        $role = $options->hash['role'] ?? '';

        if ($this->accessChecker->isGranted((string)$role)) {
            return (string)$options->fn($options->scope);
        }

        return (string)$options->inverse($options->scope);
    }
}

Common ViewHelper equivalents 

The table below lists frequently used Fluid ViewHelpers and how to handle them in Handlebars templates.

Fluid ViewHelper bridge 

As a temporary migration aid, the extension ships a viewHelper helper that invokes any registered Fluid ViewHelper directly from a Handlebars template. This lets you use existing ViewHelpers without writing a wrapper immediately.

{{viewHelper "f:format.date" date=someDate format="d.m.Y"}}

{{viewHelper "myext:widget.paginate" objects=items as="pagedItems"}}

{{#viewHelper "myext:security.ifGranted" role="ADMIN"}}
    <a href="/admin">Admin panel</a>
{{/viewHelper}}

To use ViewHelpers from a custom namespace, register the namespace first with viewHelperNamespace:

{{viewHelperNamespace "tx" "https://typo3.org/ns/Vendor/Extension/ViewHelpers"}}
{{viewHelper "tx:myHelper" someArg=value}}

Strategy overview 

The recommended path has three lanes that can be worked independently:

• Content elements rendered via tt_content.* TypoScript: Replace the content object type from FLUIDTEMPLATE to HANDLEBARSTEMPLATE one CType at a time.
• Extbase controllers: Extend HandlebarsController, then migrate templates action by action with a Fluid fallback in place.
• Shared partials / layout: Migrate the layout shell last, once all templates that depend on it have been converted.

1. Install and configure paths

   Install the extension and include the base site set without the content-element set. The content-element set replaces lib.contentElement globally; omitting it keeps all existing content elements on Fluid.

   config/sites/<site>/config.yaml

   dependencies:
     - cpsit/handlebars   # base set only — does NOT touch lib.contentElement

   Copied!

   Configure template and partial root paths for Handlebars independently of the Fluid paths:

   plugin.tx_handlebars {
       view {
           templateRootPaths {
               10 = EXT:my_sitepackage/Resources/Private/Templates/Handlebars
           }
           partialRootPaths {
               10 = EXT:my_sitepackage/Resources/Private/Partials/Handlebars
           }
       }
   }

   Copied!

   Fluid and Handlebars path registrations are completely independent, so there is no risk of one system picking up the other's files.

2. Migrate content elements one at a time

   For each content element, convert the TypoScript definition from FLUIDTEMPLATE to HANDLEBARSTEMPLATE and create the corresponding .hbs file.

   Before (Fluid):

   tt_content.tx_myext_teaser = FLUIDTEMPLATE
   tt_content.tx_myext_teaser {
       templateName = Teaser
       templateRootPaths.10 = EXT:my_extension/Resources/Private/Templates
       partialRootPaths.10 = EXT:my_extension/Resources/Private/Partials
       layoutRootPaths.10 = EXT:my_extension/Resources/Private/Layouts
       variables {
           title = TEXT
           title.field = header
       }
       dataProcessing {
           10 = TYPO3\CMS\Frontend\DataProcessing\FilesProcessor
           10 {
               references.fieldName = image
               as = images
           }
       }
   }

   Copied!

   After (Handlebars):

   tt_content.tx_myext_teaser = HANDLEBARSTEMPLATE
   tt_content.tx_myext_teaser {
       templateName = Teaser
       templateRootPaths.10 = EXT:my_extension/Resources/Private/Templates/Handlebars
       partialRootPaths.10 = EXT:my_extension/Resources/Private/Partials/Handlebars
       variables {
           title = TEXT
           title.field = header
       }
       dataProcessing {
           10 = files
           10 {
               references.fieldName = image
               as = images
           }
       }
   }

   Copied!

   All other tt_content.* definitions that are not yet migrated continue to use Fluid without any changes.

3. Migrate Extbase controllers

   For controller-based rendering, the extension provides HandlebarsViewFactory, which replaces TYPO3's default FluidViewFactory. It inspects the TypoScript configuration and returns a HandlebarsView when Handlebars configuration is present, or falls back to the Fluid view when it is not.

   Note

   The view factory is globally injected to all Extbase controllers extending ActionController, so there's no need to switch the view factory injection.

   Extend HandlebarsController:

   For controllers you own, extend \CPSIT\Typo3Handlebars\Controller\HandlebarsController instead of ActionController. The renderView() method renders the current action via Handlebars:

   EXT:my_extension/Classes/Controller/BlogController.php

   namespace Vendor\Extension\Controller;
   
   use CPSIT\Typo3Handlebars\Controller\HandlebarsController;
   use Psr\Http\Message\ResponseInterface;
   
   final class BlogController extends HandlebarsController
   {
       public function listAction(): ResponseInterface
       {
           $this->view->assign('posts', $this->postRepository->findAll());
   
           return $this->htmlResponse($this->renderView());
       }
   }

   Copied!

   The view factory resolves the template name automatically from the controller alias and action name (e.g., Blog/list.hbs for listAction). Configure paths and per-action overrides via the handlebars key in the plugin's TypoScript namespace:

   plugin.tx_myextension_myplugin {
       handlebars {
           default {
               templateRootPaths.10 = EXT:my_extension/Resources/Private/Templates/Handlebars
               partialRootPaths.10 = EXT:my_extension/Resources/Private/Partials/Handlebars
           }
       }
   }

   Copied!

   See also

   Extbase plugins for the full configuration reference, including per-controller and per-action overrides.

   Using the Fluid fallback during migration:

   When a controller action has not yet been ported, call delegateRendering() on the view to delegate to the underlying Fluid view. This keeps the action working while the template is being migrated:

   public function legacyAction(): ResponseInterface
   {
       $this->view->assign('items', $this->repository->findAll());
   
       // Render with Fluid until the .hbs template is ready
       $content = $this->view instanceof HandlebarsView
           ? $this->view->delegateRendering()
           : $this->view->render();
   
       return $this->htmlResponse((string)$content);
   }

   Copied!

4. Migrate the page layout shell

   The layout shell (the outer HTML document, header, navigation, footer) is typically the last thing to migrate because it is shared by every page. Keep the existing Fluid layout in place until all content elements and actions that reference it have been converted to Handlebars partials.

   Once all consumers are migrated, convert the Fluid layout to a Handlebars layout partial using the extend / block / content pattern described in Layouts and partials.

5. Switch the lib.contentElement default

   After every content element has been migrated to HANDLEBARSTEMPLATE, include the cpsit/handlebars-content-element site set. This sets lib.contentElement = HANDLEBARSTEMPLATE globally so that newly created content elements start from Handlebars automatically:

   config/sites/<site>/config.yaml

   dependencies:
     - cpsit/handlebars
     - cpsit/handlebars-content-element

   Copied!

Version 1.0.0 

Version 1.0.0 replaces the previous PHP-class rendering model (DataProcessor / DataProvider / Presenter) with the HANDLEBARSTEMPLATE content object. All rendering configuration moves to TypoScript; custom PHP classes are no longer the entry point.

tt_content.header = USER
tt_content.header.userFunc = Vendor\Extension\DataProcessing\HeaderProcessor->process

tt_content.header = HANDLEBARSTEMPLATE
tt_content.header {
    templateName = Header

    variables {
        header = TEXT
        header.field = header

        subheader = TEXT
        subheader.field = subheader
    }
}

tt_content.my_element {
    templateName = MyElement
}

tt_content.my_element {
    templateName = MyElement
    templateName.override.if {
        isTrue.field = tx_myext_variant
        value = special
    }
    templateName.override = MyElementSpecial
}

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

use CPSIT\Typo3Handlebars\Attribute\AsHelper;
use CPSIT\Typo3Handlebars\Renderer\Helper\Helper;
use DevTheorem\Handlebars\HelperOptions;

#[AsHelper('greet')]
final readonly class GreetHelper implements Helper
{
    public function render(HelperOptions $options): string { /* ... */ }
}

tt_content.textmedia = HANDLEBARSTEMPLATE
tt_content.textmedia {
    templateRootPaths.10 = EXT:my_extension/Resources/Private/Templates
    partialRootPaths.10 = EXT:my_extension/Resources/Private/Partials
}

Preparation 

# Clone repository
git clone https://github.com/CPS-IT/handlebars.git
cd handlebars

# Install dependencies
composer install

Development workflow 

A typical contribution workflow looks like this:

1. Apply automatic fixes

   Use the following commands to normalize and format the code base:

   # Apply all automatic fixes
   composer fix
   
   # Apply specific fixes
   composer fix:composer
   composer fix:editorconfig
   composer fix:php

   Copied!

2. Run checks

   Use composer check to run the full code quality pipeline locally. This command bundles dependency analysis, static analysis, coding style checks, and Rector in dry-run mode so that potential refactorings can be reviewed without changing files.

   # Run all checks
   composer check
   
   # Run specific checks
   composer check:deps
   composer check:refactor
   composer check:static
   composer check:style
   
   # Run specific style checks
   composer check:style:composer
   composer check:style:editorconfig
   composer check:style:php
   composer check:style:typoscript

   Copied!

3. Run refactorings

   Refactorings are intentionally separated from regular checks because they may change the code base.

   # Run all configured refactorings
   composer refactor
   
   # Run specific refactorings
   composer refactor:php

   Copied!

4. Run tests

   Run the full test suite before opening a pull request:

   # Run all tests
   ddev composer test
   ddev composer test:coverage
   
   # Run functional tests
   ddev composer test:functional
   ddev composer test:functional:coverage
   
   # Run unit tests
   ddev composer test:unit
   ddev composer test:unit:coverage
   
   # Merge coverage reports
   ddev composer test:merge-coverage

   Copied!

Coverage reports 

Code coverage reports are written to Build/tests/coverage. Open the latest merge HTML report with:

open Build/tests/coverage/html/_merged/index.html

Pull requests 

Once the changes are ready, please submit a pull request and describe what was changed and why. Ideally, the pull request references an issue that describes the problem being solved.

All documented code quality tools are executed automatically for pull requests across the currently supported PHP versions. For details, refer to the GitHub Actions workflows.