Quick start 

This page walks through the minimum steps required to render a form with Handlebars.

1. Include the site set

   Follow the site set instructions in the installation guide to add cpsit/handlebars-forms to your site's dependencies.

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

3. Create a Handlebars template

   Create a .hbs file in the Handlebars template root path configured by your EXT:handlebars installation. The default template name is Form (configurable via the handlebars_forms.view.templateName site setting), so the file should be named Form.hbs.

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

   <form id="{{formData.id}}"
         method="{{formData.method}}"
         action="{{formData.action}}"
   >
       {{#each fields}}
           {{#if template}}
               {{> (lookup . 'template')}}
           {{elseif content}}
               {{this.content}}
           {{/if}}
       {{/each}}
   
       {{#each navItems}}
           {{> '@button' this}}
       {{/each}}
   
       {{hiddenFields}}
   </form>

   Copied!

   Tip

   The hiddenFields value is an HTML string (e.g. CSRF token, page index). 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.

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