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.

1. Include the site sets

   Add the cpsit/handlebars-forms site set to your site configuration (see Site set), together with a site set providing content element rendering, e.g. cpsit/handlebars-content-element :

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

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

   Copied!

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

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

   Copied!

   See also

   Template paths in the EXT:handlebars documentation – all configuration methods and their priority order.

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

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

   Copied!

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

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

   Copied!

   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.

5. Flush caches

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