---
title: "Configuration"
manual: "Handlebars"
version: "main"
permalink: "https://docs.typo3.org/permalink/cpsit/typo3-handlebars-forms:configuration@main"
source: "Configuration/Index.rst"
rendered: "2026-09-29T09:18:02+00:00"
---

# Configuration {#configuration}

## Site settings {#site-settings}

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

-   **handlebars_forms.view.templateName**

    -   *Type:* string
    -   *Default:* `Form`

    Name of the Handlebars template used for rendering a form when no per-form
    template is configured. Corresponds to a template file in the configured
    Handlebars template root paths, e.g. `Form.hbs`.

    > [!NOTE]
    > The default `Form.hbs` template serves as placeholder to allow a smooth
    > form rendering integration. It only shows a rendering warning and must be
    > overridden by a concrete template which handles the whole rendering.

## TypoScript {#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:

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

> [!TIP]
> New to the extension? The [Quick start](https://docs.typo3.org/permalink/cpsit/typo3-handlebars-forms:quick-start@main) shows a complete, working
> `dataProcessing` block together with a matching Handlebars template.

Each block is passed to a [HANDLEBARSTEMPLATE](https://docs.typo3.org/p/cpsit/typo3-handlebars/main/en-us/Usage/ContentObject.html#content-object)
content object provided by EXT:handlebars. This means all of its properties can be used,
e.g. `templateRootPaths` and `partialRootPaths` to configure
form-specific template paths, or `variables` to pass additional values to
the template.

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
1.  Form unique identifier (e.g. `my-contact-form-123`)
1.  Original form identifier before suffixes are appended (e.g. `my-contact-form`)
1.  Form persistence identifier (the YAML file path, e.g.
    `EXT:my_extension/Resources/Private/Forms/ContactForm.form.yaml`)

### Per-form overrides {#configuration-per-form}

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

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

### Template context {#template-context}

The `templateName` key names the Handlebars template file (without extension)
that receives the data produced by the [process-form](https://docs.typo3.org/permalink/cpsit/typo3-handlebars-forms:data-processor@main) processor as its
template context.

> [!NOTE]
> The `dataProcessing` block follows the same TypoScript data-processor syntax
> used elsewhere in TYPO3 (e.g. inside `FLUIDTEMPLATE`). The
> [process-form](https://docs.typo3.org/permalink/cpsit/typo3-handlebars-forms:data-processor@main) processor identifier is provided by this extension.

See [Conditions](https://docs.typo3.org/permalink/cpsit/typo3-handlebars-forms:process-form-conditions@main) in the processor reference for details on
using `if` to conditionally omit keys from the output.