What does it do? 

The extension provides a way to render forms built with the TYPO3 Form Framework. It allows rendering of generic forms, defined by a comprehensive TypoScript rendering definition. This definition can be extended to a specific form to allow customizating the output of various forms. In addition, the extension allows to modify the build mechanisms of so called view models, which makes the whole concept very dynamic and flexible.

Features 

• Support for all default form elements
• Ability to define generic form rendering definitions
• Possibility to override form rendering for specific form definitions
• Easy to extend and customize for custom form elements
• 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-forms/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-forms

Or download it from the TYPO3 extension repository.

Site set 

The extension ships a site set that provides default TypoScript configuration and site settings. Include it in your site's config.yaml:

dependencies:
  - cpsit/handlebars-forms

The site set requires two other sets as dependencies: cpsit/handlebars-content-element (from EXT:handlebars) and typo3/form (from EXT:form). Both are declared in the extension's own set, so you do not need to list them separately.

Site settings 

The following settings are exposed through the site set and can be overridden per site.

TypoScript 

The site set sets up a TypoScript object at plugin.tx_form.handlebarsForms, where integrators define how each form is rendered. The structure is:

plugin.tx_form.handlebarsForms {
    # Applied to every form (fallback)
    default {
        templateName = {$handlebars_forms.view.templateName}

        dataProcessing {
            10 = process-form
            10 {
                # ... HBS_* configuration
            }
        }
    }

    # Override for a specific form – merged on top of "default"
    my_contact_form {
        templateName = ContactForm
    }
}

When a form is rendered, the extension looks up configuration blocks in the following order. All matching blocks are merged, with later entries winning:

1. default – applied to every form
2. Form unique identifier (e.g. my-contact-form-123)
3. Original form identifier before suffixes are appended (e.g. my-contact-form)
4. Form persistence identifier (the YAML file path, e.g. EXT:my_extension/Resources/Private/Forms/ContactForm.form.yaml)

The templateName key names the Handlebars template file (without extension) that receives the data produced by the process-form processor as its template context.

See Conditions in the processor reference for details on using if to conditionally omit keys from the output.

Per-form overrides 

To use a different template or a different data structure for a specific form, add a block keyed by the form identifier. It is merged on top of default:

plugin.tx_form.handlebarsForms {
    my_contact_form {
        templateName = ContactForm

        dataProcessing {
            10 = process-form
            10 {
                fields =< plugin.tx_form.handlebarsForms.default.dataProcessing.10.fields
                fields {
                    # Extra field type only present in this form
                    Rating {
                        template = @form-field-rating

                        value = HBS_TAG
                        value.attribute = value
                    }
                }
            }
        }
    }
}

Key resolution 

The processor iterates all keys in its configuration block and resolves each one by the following rules, applied in order:

1. Array value (no string sibling) – the sub-tree is processed recursively. The result is stored as a nested array under the key name (without trailing dot).
2. String value matching a registered content object – the content object is rendered with the dotted sub-tree as its configuration. The return value is stored under the key name.
3. String value not matching any content object – the raw string is stored as-is.

These rules mean the structure of the TypoScript block directly mirrors the structure of the resulting PHP array:

10 = process-form
10 {
    # Rule 1: nested array
    formData {
        id = HBS_TAG
        id.attribute = id

        method = HBS_TAG
        method.attribute = method
    }

    # Rule 2: content object
    label = HBS_LABEL

    # Rule 3: literal string
    staticKey = staticValue
}

Produces:

[
    'formData' => [
        'id'     => '…',   // resolved by HBS_TAG
        'method' => '…',   // resolved by HBS_TAG
    ],
    'label'     => '…',    // resolved by HBS_LABEL
    'staticKey' => 'staticValue',
]

Content object configuration 

Configuration for a content object is placed in the dotted sub-tree below the key:

id = HBS_TAG
id.attribute = id

subject = HBS_PROPERTY
subject.path = type
subject.subject = renderable

The dotted sub-tree also supports stdWrap, which is applied to the resolved value after the content object returns:

label = HBS_LABEL
label.stdWrap.case = upper

Conditions 

if is supported at two levels and behaves like the built-in TypoScript function.

It can be placed directly in the processor configuration (or in any nested sub-tree). When the condition evaluates to false, the entire block is skipped and null is returned for its parent key:

fields = HBS_RENDERABLES
fields {
    Fieldset {
        if.isTrue = 0
    }
}

The currentValue extension in if allows the condition to be evaluated against a value resolved by the processor itself rather than a static TypoScript value. It accepts a content object expression using the same syntax as the main configuration:

someField {
    if {
        currentValue = HBS_PROPERTY
        currentValue.path = required
        isTrue.current = 1
    }

    label = HBS_LABEL

    value = HBS_TAG
    value.attribute = value
}

TypoScript references 

TypoScript copy ( <) and reference ( =<) operators are fully supported. References are resolved before any key in a block is processed, so the merged configuration is what the content objects see:

Email < .Text

navItems = HBS_NAVIGATION
navItems {
    previousPage {
        # ...
    }
    nextPage < .previousPage
    submit < .previousPage
}

fields =< plugin.tx_form.handlebarsForms.default.dataProcessing.10.fields

Renderable context 

Each key in the processor configuration is resolved in the context of the current renderable. At the top level this is the FormRuntime (i.e. the whole form). When HBS_RENDERABLES iterates children, each child key is resolved in the context of that child renderable and its view model.

The active renderable and view model are accessible to all HBS_* content objects through the ValueResolutionContext they receive. This is what allows HBS_TAG to read from the rendered tag of the current element rather than a global one, and why the same HBS_LABEL call returns a different label for each iteration of HBS_RENDERABLES.

HBS_RENDERABLES 

Iterates the child renderables of the current renderable and resolves each one according to per-type configuration. Returns a list (array).

When used at the top level (form runtime as current renderable), it iterates the elements of the current page. For composite renderables such as Fieldset, it iterates their direct children.

Configuration

fields = HBS_RENDERABLES
fields {
    # Per-type configuration (key = EXT:form element type)
    Text {
        template = @form-field-text
        label = HBS_LABEL
        value = HBS_TAG
        value.attribute = value
    }

    # Fallback for types without a dedicated block
    default {
        template = @form-field-generic
    }

    # Single content object for a type (no sub-configuration)
    Honeypot = HBS_PASSTHROUGH

    # Suppress a type entirely
    SomeType {
        if.isTrue = 0
    }
}

The lookup order for each child element is: exact type key, default. If neither matches, the element is skipped.

Frontend register

While iterating, HBS_RENDERABLES writes two values to the frontend register that TypoScript conditions can read via register:

• HBS_RENDERABLES_COUNT – total number of renderables in the current iteration
• HBS_RENDERABLES_CURRENT – zero-based index of the element being processed (unset after the loop)

HBS_PROPERTY 

Reads a property from the current renderable, its view model, or the form runtime using Extbase\Reflection\ObjectAccess::getProperty(). Returns whatever type the property holds (string, array, object, …).

Configuration

Example

renderableType = HBS_PROPERTY
renderableType.path = type

# Read from the view model instead
resourcePointerFields = HBS_PROPERTY
resourcePointerFields {
    subject = viewModel
    path = children?[resourcePointerFields?]
}

HBS_TAG 

Reads an HTML attribute (or the inner content) from the tag rendered by the current renderable's view model. The view model must implement TagAwareViewModel; this is the case for all view models built by the built-in ViewModelBuilder implementations. Returns a SafeString (Handlebars will not escape the value).

The tag reflects the final output of the Fluid ViewHelper responsible for rendering the renderable. For example, the root FormRuntime object is rendered by the <formvh:form> view helper, so HBS_TAG on it returns attributes (or content) of the <form> tag that view helper produces. Similarly, a Text element is rendered by <f:form.textfield>, so HBS_TAG exposes the attributes of the resulting <input> tag.

Configuration

Example

# Read the "id" attribute of the rendered <input> tag
id = HBS_TAG
id.attribute = id

# Read the inner HTML of the rendered tag (e.g. <textarea> content)
content = HBS_TAG

HBS_LABEL 

Returns the translated label of the current renderable. If the current view model is a FormFieldViewModel, the label is taken from the view model's pre-resolved label property; otherwise it falls back to $renderable->getLabel(). Returns a string.

Configuration

No configuration keys. stdWrap is supported.

label = HBS_LABEL

HBS_FORM_VALUE 

Reads the current or submitted value of the form element. Internally wraps EXT:form's <formvh:renderFormValue> view helper and exposes its result as a FormValueViewModel.

Without an output key the resolved processedValue is returned directly.

Output instructions

The output key accepts one of the following built-in instructions:

Examples

# Summary page: show the human-readable value
value = HBS_FORM_VALUE
value.output = PROCESSED_VALUE

# Multi-value field: iterate over each option
values = HBS_FORM_VALUE
values {
    output = EACH_PROCESSED_VALUE
    output {
        label = HBS_LABEL

        selected = HBS_PROPERTY
        selected.path = selected
    }
}

HBS_NAVIGATION 

Resolves the navigation buttons (previous page, next page / submit) for the current form page. Returns a list of processed items. Each item is built by the sub-configuration keyed by button role.

Button roles

• previousPage – previous-page button (only present when not on the first page)
• nextPage – next-page button (only present when not on the last page)
• submit – submit button (only present on the last page)

Within each role block, HBS_TAG and HBS_LABEL operate on the rendered <button> tag and the translated button label respectively.

Example

navItems = HBS_NAVIGATION
navItems {
    previousPage {
        label = HBS_LABEL

        name = HBS_TAG
        name.attribute = name

        value = HBS_TAG
        value.attribute = value
    }

    nextPage < .previousPage
    submit < .previousPage
}

HBS_PASSTHROUGH 

Renders the current renderable using EXT:form's standard Fluid partials and returns the result as a SafeString. Useful for elements that do not need a custom template (e.g. Honeypot, ContentElement) or as a fallback.

Configuration

Additional TypoScript keys are converted to plain PHP variables and passed to the Fluid rendering context:

Honeypot {
    content = HBS_PASSTHROUGH
}

# Pass extra variables to the Fluid partial
SomeElement {
    content = HBS_PASSTHROUGH
    content {
        myVariable = someValue
    }
}

HBS_CHILDREN 

Returns the children of the current view model as a list. The view model must implement CompositeViewModel (e.g. ViewModelCollection). Returns null when the view model has no children.

Each child is processed using the sub-configuration of HBS_CHILDREN.

Frontend register

While iterating, HBS_CHILDREN writes two values to the frontend register that TypoScript conditions can read via register:

• HBS_CHILDREN_COUNT – number of children
• HBS_CHILDREN_CURRENT – index of the child being processed (unset after the loop)

Example

options = HBS_CHILDREN
options {
    label = HBS_LABEL

    checked = HBS_TAG
    checked.attribute = checked
}

HBS_TRANSLATE_PROPERTY 

Translates a renderable property using EXT:form's <formvh:translateElementProperty> view helper.

Configuration

Example

placeholder = HBS_TRANSLATE_PROPERTY
placeholder.property = placeholder

submitButtonLabel = HBS_TRANSLATE_PROPERTY
submitButtonLabel {
    property = submitButtonLabel
    argumentName = renderingOptionProperty
}

HBS_TRANSLATE_ERROR 

Returns the translated message for a specific validation error code on the current renderable. Uses EXT:form's <formvh:translateElementError> view helper internally.

Configuration

Example

requiredError = HBS_TRANSLATE_ERROR
requiredError.errorCode = 1221560718

HBS_VALIDATION_RESULTS 

Returns the Extbase validation results for the current renderable. Without an output instruction the raw Result object is returned.

Output instructions

Example

errors = HBS_VALIDATION_RESULTS
errors {
    output = EACH_RENDERABLE
    output {
        label = HBS_LABEL

        message = HBS_VALIDATION_RESULTS
        message.output = ERROR_MESSAGE
    }
}

HBS_VH_CONTENT 

Returns the output of the view helper that was used to build the current view model. The view model must be a ViewHelperContainedViewModel. HTML strings are returned as SafeString (no double-escaping).

No configuration keys beyond stdWrap.

Example

# Render the raw <input> tag produced by the view helper
content = HBS_VH_CONTENT

Supported renderables 

Unsupported renderables 

Implementing the interface 

The ViewModelBuilder interface declares two methods:

interface ViewModelBuilder
{
    public function build(
        RootRenderableInterface $renderable,
        RenderingContext $renderingContext,
    ): ViewModel;

    public function supports(RootRenderableInterface $renderable): bool;
}

supports() is called first; return true only for the renderable types your builder handles. build() is then called to produce the view model.

The easiest starting point is to extend \CPSIT\Typo3HandlebarsForms\Domain\ViewModel\Builder\AbstractViewModelBuilder. It takes care of the boilerplate:

• Wraps the rendering inside a simulated <formvh:renderRenderable> context so EXT:form's state is correct.
• Applies grid-column classes when the renderable is inside a GridRow.
• Provides renderAdditionalAttributes() to resolve fluidAdditionalAttributes from the element's properties.

Override renderRenderable() to produce your custom view model; return null from it to fall back to the default ViewHelperContainedViewModel that wraps the full rendered output of the view helper.

Minimal example

use CPSIT\Typo3HandlebarsForms;
use TYPO3\CMS\Fluid;
use TYPO3\CMS\Form;

final class RatingViewModelBuilder extends Typo3HandlebarsForms\Domain\ViewModel\Builder\AbstractViewModelBuilder
{
    protected array $supportedTypes = ['Rating'];

    protected function renderRenderable(
        Form\Domain\Model\Renderable\RootRenderableInterface $renderable,
        Fluid\Core\Rendering\RenderingContext $renderingContext,
    ): ?Typo3HandlebarsForms\Domain\ViewModel\ViewModel {
        $result = $this->viewHelperInvoker->invoke(
            $renderingContext,
            Fluid\ViewHelpers\Form\TextfieldViewHelper::class,
            [
                'type'     => 'number',
                'property' => $renderable->getIdentifier(),
                'id'       => $renderable->getUniqueIdentifier(),
                'additionalAttributes' => $this->renderAdditionalAttributes($renderable, $renderingContext),
            ],
        );

        return new Typo3HandlebarsForms\Domain\ViewModel\ViewHelperContainedViewModel($renderable, $result);
    }
}

Registration 

The ViewModelBuilder interface carries a #[AutoconfigureTag('handlebars_forms.view_model_builder')] attribute. Any class that implements the interface is therefore registered automatically via Symfony DI when autowiring is enabled (the default for extensions that include a Configuration/Services.yaml with autowire: true).

No explicit YAML service definition is needed.

Builder priority 

When multiple builders claim the same renderable type via supports(), the first one in the service iterator wins. The iterator order is determined by the Symfony DI priority tag attribute. Built-in builders are registered without an explicit priority (i.e. priority 0).

To ensure your builder runs before a built-in one, set a higher priority:

# Configuration/Services.yaml
Vendor\MyExtension\Domain\ViewModel\Builder\RatingViewModelBuilder:
    tags:
        - name: handlebars_forms.view_model_builder
          priority: 10

Choosing a view model type 

Pick the view model type that best matches what your TypoScript configuration will consume:

Implementing a custom content object 

The abstract base class has one abstract method to implement:

abstract protected function resolve(
    array $configuration,
    ValueResolutionContext $context,
): mixed;

$configuration is the TypoScript sub-tree below your content object's key. $context exposes the current state:

• $context->renderable – the EXT:form renderable being processed
• $context->viewModel – its view model
• $context->formRuntime – the active form runtime
• $context->renderingContext – the Fluid rendering context

Return any value. Strings are returned directly to the TypoScript tree. Non-string values (arrays, objects) are automatically stored in the ValueCollector under a placeholder key; ProcessFormProcessor replaces the placeholder with the real value after the full tree has been resolved.

Example

use CPSIT\Typo3HandlebarsForms\ContentObject;
use Symfony\Component\DependencyInjection;

#[DependencyInjection\Attribute\AutoconfigureTag(
    'frontend.contentobject',
    ['identifier' => 'MY_CUSTOM_COBJ'],
)]
final class MyCustomContentObject extends ContentObject\AbstractHandlebarsFormsContentObject
{
    protected function resolve(
        array $configuration,
        ContentObject\Context\ValueResolutionContext $context,
    ): mixed {
        return $context->renderable->getProperties()[$configuration['key'] ?? ''] ?? null;
    }
}

Use it in TypoScript like any built-in content object:

myValue = MY_CUSTOM_COBJ
myValue.key = someProperty

stdWrap support 

stdWrap is handled automatically by the base class for every HBS_* and custom content object. If resolve() returns a stringable value, stdWrap is applied directly to it. If the value is non-stringable, stdWrap receives an empty string but the original value is set as the currentValue so TypoScript conditions inside stdWrap can still read it.

Registration 

The #[AutoconfigureTag('frontend.contentobject', ['identifier' => '...'])] attribute is sufficient for registration when the class lives in a directory that is autowired. No explicit YAML service definition is needed.

The identifier must be globally unique across all loaded extensions. Prefixing it with your vendor name (e.g. MYVENDOR_FOO) avoids collisions.

Recursing into the TypoScript tree 

$context->process() re-invokes the ProcessFormProcessor pipeline with an arbitrary TypoScript configuration array. Its primary purpose is to let your content object re-process the current (or a different) renderable under a different configuration block — for example, to apply a sub-section of your own configuration, or to switch the active renderable or view model entirely before the pipeline runs.

protected function resolve(
    array $configuration,
    ContentObject\Context\ValueResolutionContext $context,
): mixed {
    $subConfiguration = $configuration['items.'] ?? [];

    if (!is_array($subConfiguration)) {
        return null;
    }

    return $context->process($subConfiguration);
}

To process a different renderable or view model, pass them as named arguments:

$context->process($subConfig, renderable: $otherRenderable, viewModel: $otherViewModel);

Context stack 

The ContextStack is a shared singleton (shared: true in DI). It holds the stack of ValueResolutionContext objects pushed by ProcessFormProcessor as it walks the TypoScript tree.

Custom content objects receive the current context as a direct argument to resolve() – injecting ContextStack directly is not necessary and is considered internal API.

Preparation 

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

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