---
title: "Quick start"
manual: "Handlebars"
version: "main"
permalink: "https://docs.typo3.org/permalink/cpsit/typo3-handlebars-forms:quick-start@main"
source: "Usage/QuickStart.rst"
rendered: "2026-09-29T09:18:02+00:00"
---

# Quick start {#quick-start}

This page walks through a minimal working example: rendering a form built with
the TYPO3 Form Framework using a single Handlebars template. It assumes the
extension is already [installed](https://docs.typo3.org/permalink/cpsit/typo3-handlebars-forms:installation@main).

1.  Include the site sets

    Add the `cpsit/handlebars-forms` site set to your site configuration
    (see [Site set](https://docs.typo3.org/permalink/cpsit/typo3-handlebars-forms:site-set@main)), together with a site set providing
    [content element rendering](https://docs.typo3.org/permalink/cpsit/typo3-handlebars-forms:site-set-content-rendering@main), e.g.
    `cpsit/handlebars-content-element`:

    **config/sites/\<my-site>/config.yaml**

    ```yaml
    dependencies:
      - cpsit/handlebars-content-element
      - cpsit/handlebars-forms
    ```
1.  Configure template paths

    Declare where your `.hbs` files are located using the site settings
    provided by the `cpsit/handlebars` site set (from EXT:handlebars), which is
    included automatically by the `cpsit/handlebars-forms` site set:

    **config/sites/\<my-site>/settings.yaml**

    ```yaml
    handlebars.view.templateRootPath: 'EXT:my_sitepackage/Resources/Private/Templates/Handlebars'
    handlebars.view.partialRootPath: 'EXT:my_sitepackage/Resources/Private/Partials/Handlebars'
    ```

    > [!NOTE]
    > **See also**
    >
    > [Template paths](https://docs.typo3.org/p/cpsit/typo3-handlebars/main/en-us/Configuration/TemplatePaths.html#template-paths) in the EXT:handlebars
    > documentation – all configuration methods and their priority order.
1.  Configure TypoScript

    Add a `dataProcessing` block under
    `plugin.tx_form.handlebarsForms.default` that maps EXT:form renderables
    to `HBS_*` content objects. The array built by the processor becomes the
    Handlebars template context.

    The example below produces a `fields` array and a `navItems`
    array from the current form page, plus a `hiddenFields` string:

    ```typoscript
    plugin.tx_form.handlebarsForms {
        default {
            dataProcessing {
                10 = process-form
                10 {
                    formData {
                        id = HBS_TAG
                        id.attribute = id

                        action = HBS_TAG
                        action.attribute = action

                        method = HBS_TAG
                        method.attribute = method
                    }

                    fields = HBS_RENDERABLES
                    fields {
                        default {
                            template = @form-field-generic

                            id = HBS_TAG
                            id.attribute = id

                            name = HBS_TAG
                            name.attribute = name

                            label = HBS_LABEL

                            value = HBS_TAG
                            value.attribute = value
                        }

                        # Per-type overrides inherit from default via TypoScript copy operator
                        Text < .default
                        Text {
                            template = @form-field-text
                        }

                        Email < .Text

                        # Suppress Honeypot in the template; render it verbatim instead
                        Honeypot {
                            content = HBS_PASSTHROUGH
                        }
                    }

                    navItems = HBS_NAVIGATION
                    navItems {
                        previousPage {
                            label = HBS_LABEL

                            name = HBS_TAG
                            name.attribute = name

                            value = HBS_TAG
                            value.attribute = value
                        }

                        nextPage < .previousPage
                        submit < .previousPage
                    }

                    hiddenFields = HBS_TAG
                }
            }
        }
    }
    ```
1.  Create a Handlebars template

    Create the template file at the template root path declared above. The default
    template name is `Form` (configurable via the
    [handlebars_forms.view.templateName](https://docs.typo3.org/permalink/cpsit/typo3-handlebars-forms:confval-handlebars-forms-view-templatename@main)
    site setting), so the file must be named `Form.hbs`.

    The template receives the data built by the `process-form` processor
    directly as its context:

    **EXT:my_sitepackage/Resources/Private/Templates/Handlebars/Form.hbs**

    ```handlebars
    <form id="{{formData.id}}"
          method="{{formData.method}}"
          action="{{formData.action}}"
    >
        {{#each fields}}
            {{#if template}}
                {{> (lookup . 'template')}}
            {{else if content}}
                {{this.content}}
            {{/if}}
        {{/each}}

        {{#each navItems}}
            {{> '@button' this}}
        {{/each}}

        {{hiddenFields}}
    </form>
    ```

    > [!TIP]
    > The `hiddenFields` value is an HTML string (e.g. page index,
    > `trustedProperties`, object identity). It is emitted by EXT:form's
    > `<f:form>` view helper and must be output without escaping. In Handlebars
    > this is done automatically when the value is a `SafeString` – which is
    > exactly what `HBS_TAG` (used without `attribute`)
    > returns when wrapping tag content.

    > [!NOTE]
    > The partials referenced in this example (`@form-field-generic`,
    > `@form-field-text` and `@button`) must be created in the partial
    > root path as well. The `@` prefix looks up a partial by its bare
    > filename, see [Referencing templates and partials](https://docs.typo3.org/p/cpsit/typo3-handlebars/main/en-us/Usage/Templates.html#templates-names).
1.  Flush caches

    After editing TypoScript or site settings, flush the TYPO3 caches.

## Next steps {#quick-start-next-steps}

-   [Data processor](https://docs.typo3.org/permalink/cpsit/typo3-handlebars-forms:data-processor@main) – full reference for the data processor, including key
    resolution rules, conditions and TypoScript references
-   [Content objects](https://docs.typo3.org/permalink/cpsit/typo3-handlebars-forms:content-objects@main) – reference for all available `HBS_*` content
    objects with their configuration options
-   [Per-form overrides](https://docs.typo3.org/permalink/cpsit/typo3-handlebars-forms:configuration-per-form@main) – use a different template or data structure for
    a specific form