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/archives/C0281DBRFCZ
• GitHub: https://github.com/CPS-IT/handlebars/issues

Security Policy 

Please read our security policy if you discover a security vulnerability in this extension.

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 {
        pageTitle = TEXT
        pageTitle.data = page:title

        campaign = TEXT
        campaign.field = campaign
    }
}

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

Data sources 

iterable is resolved exactly like dataSource on process-each — see Resolving a data payload (dataSource / data) for the full syntax, including what happens when multiple references are configured. It just uses a processor-specific option name instead of the generic dataSource . iterable.current uses the content object's current value instead (see Using the content object's current value).

This is what allows iterable to refer to a value placed into processedData by a preceding processor's as option, or to a variable an Extbase controller assigned directly to the view (Extbase-assigned view variables end up in processedData too, under the assigned key).

Usage 

final class NewsController extends HandlebarsController
{
    public function listAction(): ResponseInterface
    {
        $this->view->assign('news', $this->newsRepository->findAll());

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

plugin.tx_myextension_news.handlebars {
    News::list {
        dataProcessing {
            10 = iterable-to-array
            10 {
                iterable = processedData:news
                as = newsItems
            }
        }
    }
}

Processing individual items 

Each converted item is exposed to a nested dataProcessing chain as currentValue , reachable as contentObjectConfiguration:currentValue (see Data sources). This only happens when a nested chain is actually configured, so plain conversions are left untouched:

dataProcessing {
    10 = iterable-to-array
    10 {
        iterable = processedData:news
        as = newsItems

        dataProcessing {
            10 = object-access
            10 {
                object = contentObjectConfiguration:currentValue
                path = title
                as = title
            }
        }
    }
}

Properties 

iterable

Data source reference(s) the value to convert is read from (see Data sources). Required.

as

Target key in the processed data array the resulting array is stored under. Default: result .

preserveKeys

Boolean. When 1 , the original keys of the iterable (e.g. array keys or Generator keys) are preserved. When 0 , the result is reindexed as a plain list. Default: 0 .

dataProcessing

Nested data processors, run for each item of the converted array (see Processing individual items).

If iterable is not configured, or the resolved value is not iterable, a warning is logged and the processed data is returned unchanged.

Data sources 

file is resolved exactly like object on object-access — see Resolving a data payload (dataSource / data) for the full syntax. It just uses a processor-specific option name instead of the generic dataSource .

Usage 

tt_content.textpic = HANDLEBARSTEMPLATE
tt_content.textpic {
    templateName = @textpic

    dataProcessing {
        10 = files
        10 {
            references.fieldName = image
            as = files
        }

        20 = media
        20 {
            file = processedData:files.0
            as = image

            config {
                image {
                    # options for a registered "image" media processor
                }
            }
        }
    }
}

The first file resolved by the core files processor is passed to media , which picks whichever registered media processor's supports() method matches it first — here, a media processor registered under the name image — and stores its result under image .

Properties 

file

Data source reference the resource is read from (see Data sources). Required.

as

Target key in the processed data array the media processor's result is stored under. Default: result .

config.<name>

Configuration passed to the media processor registered under <name> . Only applied if that processor actually matches the resolved resource.

If file cannot be resolved, or no registered media processor supports the resolved resource, a warning is logged and the processed data is returned unchanged.

Data sources 

object is resolved exactly like dataSource on process-each — see Resolving a data payload (dataSource / data) for the full syntax, including what happens when multiple references are configured. It just uses a processor-specific option name instead of the generic dataSource . object.current uses the content object's current value instead (see Using the content object's current value).

This is what allows object to refer to a value placed into processedData by a preceding processor's as option, or to a variable an Extbase controller assigned directly to the view (Extbase-assigned view variables end up in processedData too, under the assigned key).

Usage 

dataProcessing also runs for Extbase plugins whose controller extends HandlebarsController, since HandlebarsView renders through the same HANDLEBARSTEMPLATE content object under the hood. An action that assigns a domain object to the view makes that object available to object-access under the assigned key:

final class BlogController extends HandlebarsController
{
    public function showAction(Post $post): ResponseInterface
    {
        $this->view->assign('post', $post);

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

plugin.tx_myextension_blog.handlebars {
    Blog::show {
        dataProcessing {
            # Pull the related category's title off the assigned "post" object
            10 = object-access
            10 {
                object = processedData:post
                path = category.title
                as = categoryTitle
            }
        }
    }
}

Properties 

object

Data source reference(s) the source object is read from (see Data sources). Required.

path

Property path passed to TYPO3Fluid\Fluid\Core\Variables\StandardVariableProvider::getByPath() . Supports plain property names as well as dot-separated nested paths (e.g. category.title ). Required.

as

Target key in the processed data array the resolved value is stored under. Default: result .

If object is not configured, or the resolved value is not an object, or path is missing, or path is not a gettable property on the resolved object, a warning is logged and the processed data is returned unchanged.

When the resolved value is itself an array, it is run through the standard TYPO3 dataProcessing chain configured on this processor, just like TYPO3's own menu or database-query processors do for their items.

Resolving the items to iterate 

The value to iterate over is resolved in the following order:

1. dataSource , if configured — see Resolving a data payload (dataSource / data) for how it is resolved, including what happens when multiple references are configured, and Using the content object's current value for dataSource.current .
2. Otherwise, an inline data array configured directly on this processor.
3. Otherwise, a data key already present in processedData . This makes process-each usable as a nested processor inside iterable-to-array or object-access — both of which wrap each item as data for their own nested dataProcessing chain — without having to repeat dataSource explicitly.

If none of these yield an iterable value, the processed data is returned unchanged.

Usage 

tt_content.textpic = HANDLEBARSTEMPLATE
tt_content.textpic {
    templateName = @textpic

    dataProcessing {
        10 = files
        10 {
            references.fieldName = image
            as = files
        }

        20 = process-each
        20 {
            dataSource = processedData:files
            as = processedFiles

            dataProcessing {
                10 = object-access
                10 {
                    object = contentObjectConfiguration:currentValue
                    path = publicUrl
                    as = url
                }

                20 = object-access
                20 {
                    object = contentObjectConfiguration:currentValue
                    path = fileType
                    as = type
                }
            }
        }
    }
}

Each file reference resolved by the core files processor is made available to the nested dataProcessing chain as currentValue , reachable as contentObjectConfiguration:currentValue (see Data sources), so object-access can pull individual properties off it. The per-item results are collected — keyed by the original array keys — under processedFiles .

Per-item processing 

Two mechanisms are available for each item, and can be combined:

variables

A variables block, processed exactly like the top-level variables of HANDLEBARSTEMPLATE , but with the content object's current value set to the item. Use current = 1 (instead of field ) to reference the item itself:

20 = process-each
20 {
    dataSource = processedData:tags
    as = processedTags

    variables {
        label = TEXT
        label.current = 1
        label.case = upper
    }
}

Copied!

data and current are reserved and cannot be used as variable names here.

dataProcessing

A standard nested dataProcessing chain (see Usage), with the item exposed as currentValue . Its result is merged with — and overrides — whatever variables produced for the same item.

Properties 

data

Inline data to iterate over, used if dataSource is not configured (see Resolving the items to iterate).

dataSource

Data source(s) to read the iterable from (see Resolving the items to iterate). dataSource.current uses the content object's current value instead (see Using the content object's current value).

as

Target key in the processed data array the resulting (keyed) array is stored under. Default: result .

variables

Per-item variables block (see Per-item processing).

dataProcessing

Per-item nested data processors (see Per-item processing).

Data sources 

as , merge and variables are read from this processor's own configuration block ( processorConfiguration ) only. table is also read from there, but falls back to a same-named key already present in processedData — this is why table , once set by an outer processor (e.g. database-query ), can be picked up by a nested process-variables without being repeated explicitly. See Data sources for what these two sources contain.

The preProcessing and postProcessing hooks receive the full DataSourceCollection , so custom DataSourceAwareProcessor implementations have access to all four sources (see DataSourceAwareProcessor).

Choosing which record to process 

By default, the field option of a variables entry resolves against the current content element's own record. Configure dataSource (or an inline data array) to process a different record or array instead — see Resolving a data payload (dataSource / data) for how it is resolved, and Using the content object's current value for dataSource.current . If the resolved payload is not an array, it is ignored and the current record's own field values are used instead.

Standalone usage 

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

Nested inside another processor 

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

Properties 

variables

Variables to process. Same syntax as the top-level variables in HANDLEBARSTEMPLATE .

table

Database table of the record to use as the data source for field lookups. Defaults to the current content element table.

data

Inline data used as the field-lookup source for variables , if dataSource is not configured (see Choosing which record to process).

dataSource

Data source(s) to use as the field-lookup source for variables , instead of the current record (see Choosing which record to process).

as

Target key in the processed data array. When set, the processed variables are stored under this key. When omitted, the processed variables replace (or merge into) the root of the processed data.

merge

Boolean. When 1 and as is omitted, the processed variables are merged into the existing processed data rather than replacing it. When as is set and the key already holds an array, the processed variables are merged into that array. Default: 0 .

if

Standard TypoScript if condition. When the condition evaluates to false, the processor is skipped and the processed data is returned unchanged.

preProcessing

Data source aware processors run before variables are processed.

postProcessing

Data source aware processors run after variables are processed.

Properties 

pattern

Regular expression used to identify marker keys. The first capture group becomes the resolved variable name. Default: ###(.*?)###

removeNonMatchingMarkers

Boolean. When 1 , variable keys that still match the marker pattern after resolution (i.e., no value was found for them) are removed from the processed data. Default: 0 .

Overview 

Not every source necessarily holds what its name suggests. A processor invoked through TYPO3's dataProcessing chain always receives a contentObjectConfiguration , but once it is nested inside another processor's own dataProcessing , that value is no longer the top-level HANDLEBARSTEMPLATE configuration — it is whatever the parent processor forwards instead (its own config block, for example). The collection built for HANDLEBARSTEMPLATE 's own preProcessing / postProcessing hooks, which run before dataProcessing itself, sets only contentObjectRenderer and processorConfiguration ; contentObjectConfiguration and processedData are genuinely absent there.

Priority order 

When a lookup is not restricted to a specific source, all sources that are actually available are searched in priority order, highest first:

1. processorConfiguration
2. processedData
3. contentObjectRenderer
4. contentObjectConfiguration

The first source that has the requested key wins; sources are never merged for this kind of lookup. This is why an option like table , set by an outer processor, can be picked up by a nested processor without being repeated explicitly — as long as the nested processor actually queries that source (some processors restrict a given option to a specific source, or a specific subset, rather than searching all four).

Reaching into nested keys 

A lookup key may use / to reach into a nested array within a single data source, e.g. some/nested/key . Each segment is looked up literally, one level at a time; the lookup fails (and any configured default value is used) as soon as one segment does not exist.

A key is otherwise always matched literally, dots and all. This matters for raw TypoScript arrays, which store sub-properties of a key under that same key with a literal trailing dot appended (e.g. dataProcessing. for the contents of a dataProcessing { ... } block) — such a key is looked up as-is and is not itself treated as a path.

Resolving a data payload (dataSource / data) 

process-each and process-variables accept a dataSource (or inline data ) option to pick the actual payload they operate on, independently of whatever their own configuration otherwise resolves from the four sources above. iterable-to-array and object-access use the exact same mechanism under a processor-specific option name — iterable and object respectively — instead of the generic dataSource .

dataSource (or the processor-specific option name)

One or more data source references, each optionally scoped to a sub-path with a colon (e.g. processedData:files ). The sub-path itself may use / to reach further into a nested key (e.g. processedData:files/0 ) — see Reaching into nested keys. A single reference is resolved and used as-is, whatever its type — it is not coerced into an array.

Multiple references, configured as a TypoScript array with numeric keys, are resolved in ascending key order:

• If every reference resolves to an array, they are merged, with later references overriding earlier ones on key conflicts.
• If any reference does not resolve to an array, the last resolved reference wins outright — all earlier references, including any that were arrays, are discarded rather than partially merged.

A warning is logged, and the payload cannot be resolved, if the option is empty, references an unsupported data source identifier, a data source that is missing in the current context, or a sub-path that does not exist within a data source. Note that an unconfigured option (rather than one configured with an invalid value) is not itself an error — see the fallback below and each processor's own documentation for what happens next.

data

Inline data, used as a fallback if the option above is not configured at all. This fallback always uses the fixed key data ( data. for an inline array in processorConfiguration , or a plain data key already present in processedData ), regardless of what the primary option is called for a given processor.

See each processor's own documentation for further, processor-specific fallbacks once neither option yields a value.

Using the content object's current value 

Setting current = 1 as a sub-property of dataSource (or the processor-specific option name) bypasses the resolution described above entirely and uses the content object's current value — see ContentObjectRenderer::getCurrentVal() — as the payload instead:

dataSource {
    current = 1
}

This is most useful for a nested processor that operates directly on the value a parent process-each set as current for the item being processed, without having to route that value through processedData or contentObjectConfiguration:currentValue first.

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 mirror the processorConfiguration , processedData , contentObjectRenderer and contentObjectConfiguration identifiers described in Data sources.

The $key argument may use / to reach into a nested array within the searched source(s), e.g. $collection->resolve('some/nested/key') — see Reaching into nested keys.

By default, a key (or path segment) that cannot be found in any searched source simply yields the given $default value ( null if none is given). Pass optional: false to make resolve() throw \Exception\PathIsMissingInDataSource instead, once none of the searched sources match and no default is configured:

use CPSIT\Typo3Handlebars\Exception;

try {
    $value = $collection->resolve('some/nested/key', optional: false);
} catch (Exception\PathIsMissingInDataSource $exception) {
    // None of the searched sources had "some/nested/key"
}

Resolving a data payload via a configurable keyword 

Processors often accept a configuration option that itself points at the payload to work with — for example, an iterable option naming the data source to iterate over (see Resolving a data payload (dataSource / data) for the full resolution rules). DataSourceProvider::provide() covers this pattern in one call: it reads the option named by its $keyword argument (default dataSource ) from DataSource::ProcessorConfiguration and resolves it. Since DataSourceAwareProcessor implementations are instantiated via GeneralUtility::makeInstance() , DataSourceProvider can be injected through the constructor like any other service:

use CPSIT\Typo3Handlebars\DataProcessing\DataSource\DataSourceProvider;
use CPSIT\Typo3Handlebars\Exception;

final readonly class MyPreProcessor implements DataSourceAwareProcessor
{
    public function __construct(
        private DataSourceProvider $dataSourceProvider,
    ) {}

    public function process(
        array $variables,
        DataSourceCollection $collection,
        ContentObjectRenderer $contentObjectRenderer,
    ): array {
        try {
            // Resolves the "iterable" processor option, e.g. "processedData:news"
            $variables['items'] = $this->dataSourceProvider->provide($collection, 'iterable');
        } catch (
            Exception\DataSourceIsNotSupported
            | Exception\DataSourceIsMissingInCollection
            | Exception\PathIsMissingInDataSource
        ) {
            // The "iterable" option is not configured, or invalid
        }

        return $variables;
    }
}

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

namespace Vendor\Extension\Renderer\Template\Path;

use CPSIT\Typo3Handlebars\Renderer\Template\Path\PathProvider;
use Symfony\Component\DependencyInjection\Attribute\AsTaggedItem;
use TYPO3\CMS\Core\Site\SiteFinder;

#[AsTaggedItem(priority: 25)]
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;
    }
}

The class is picked up automatically because PathProvider carries #[AutoconfigureTag('handlebars.template_path_provider')] . No extra Services.yaml entry is needed beyond standard autowiring. The #[AsTaggedItem(priority: ...)] attribute on the class determines merge order; without it, the provider defaults to priority 0.

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

isCacheable ( )

Return true if the variables provided by this provider may be cached. Return false for request-dependent variables. If any registered provider returns false , the merged VariableBag result is not cached and is recomputed on every access.

returntype

bool

namespace Vendor\Extension\Renderer\Variables;

use CPSIT\Typo3Handlebars\Renderer\Variables\VariableProvider;
use Symfony\Component\DependencyInjection\Attribute\AsTaggedItem;
use TYPO3\CMS\Core\Site\SiteFinder;

#[AsTaggedItem(priority: 10)]
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 isCacheable(): bool
    {
        return true;
    }

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

Like PathProvider , the class is picked up automatically via #[AutoconfigureTag('handlebars.variable_provider')] on the interface. The #[AsTaggedItem(priority: ...)] attribute on the class determines merge order; without it, the provider defaults to priority 0.

The interface 

interface MediaProcessor

Fully qualified name

\CPSIT\Typo3Handlebars\DataProcessing\Media\MediaProcessor

process ( contentObjectRenderer, resource, configuration = [])

Process the given resource and return the resulting array, which is stored under media 's as key.

param ContentObjectRenderer contentObjectRenderer

The current content object renderer.

param resource

The resolved resource — a core ResourceInterface or an Extbase File / FileReference .

param array configuration

This processor's slice of config.<name> .

returntype

array

supports ( resource)

Return true if this processor can handle the given resource. Called for every registered media processor, in priority order, until one returns true .

param mixed resource

The resolved resource, of unknown type.

returntype

bool

Implement a media processor 

Implementations are auto-registered because the interface itself carries #[AutoconfigureTag('handlebars.media_processor')] . The #[AsTaggedItem('<name>')] attribute on the implementing class both determines matching order among several processors (higher priority is tried first, default 0, same as PathProvider and VariableProvider) and gives the processor its <name> , i.e. the key under which media looks up its config.<name> block.

namespace Vendor\Extension\DataProcessing\Media;

use CPSIT\Typo3Handlebars\DataProcessing\Media\MediaProcessor;
use Symfony\Component\DependencyInjection\Attribute\AsTaggedItem;
use TYPO3\CMS\Core\Resource\AbstractFile;
use TYPO3\CMS\Core\Resource\ResourceInterface;
use TYPO3\CMS\Extbase\Domain\Model\File;
use TYPO3\CMS\Extbase\Domain\Model\FileReference;
use TYPO3\CMS\Frontend\ContentObject\ContentObjectRenderer;

#[AsTaggedItem('download')]
final readonly class DownloadProcessor implements MediaProcessor
{
    public function process(
        ContentObjectRenderer $contentObjectRenderer,
        ResourceInterface|File|FileReference $resource,
        array $configuration = [],
    ): array {
        return [
            'url' => $resource->getPublicUrl(),
            'label' => $configuration['label'] ?? $resource->getName(),
        ];
    }

    public function supports(mixed $resource): bool
    {
        return $resource instanceof AbstractFile && !$resource->isImage();
    }
}

With this registered, config.download.label becomes available wherever media is used.

Typed configuration with ConfigurableProcessor 

Mapping configuration by hand, as above, is fine for a couple of options. For more involved configuration, extend the abstract \CPSIT\Typo3Handlebars\DataProcessing\Media\ConfigurableProcessor instead, which uses cuyz/valinor to map the raw configuration array onto a typed, immutable configuration object before processFile() is called:

/**
 * @extends ConfigurableProcessor<MyConfiguration>
 */
final class MyProcessor extends ConfigurableProcessor
{
    public function processFile(
        ContentObjectRenderer $contentObjectRenderer,
        ResourceInterface|File|FileReference $resource,
        Configuration $configuration,
    ): array {
        // $configuration is an instance of MyConfiguration
    }

    public function supports(mixed $resource): bool
    {
        // ...
    }

    protected function getConfigurationClass(): string
    {
        return MyConfiguration::class;
    }
}

MyConfiguration only needs to implement the empty marker interface \CPSIT\Typo3Handlebars\DataProcessing\Media\Configuration\Configuration and declare its accepted options as constructor-promoted properties.

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 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.