Setting up Forms

 Last Edited: Sep 24, 2019

Creating Forms

To create a new webform, navigate to CMS / Forms on the left-hand menu and then click the blue “+ Add New Form” button.

Form Setup:

  • Form Name - This field is used to name your form, please do not use specical characters.
  • Form Redirect - This field specifies which page the user is redirected to after they have submitted your form. It requires no initial /, for example; contact or services/my-service.

Default Required Fields:

  • Name - User submitting the form is required to enter their name.
  • Email Address - User submitting the form is required to enter their email.

Custom Field Types:

  • Text (String) - Single line text field, used for short text inputs.
  • Text (Multiline) - Multiline text field, used for longer text inputs.
  • Checkbox - Comma seperated e.g. Checkbox 1, Checkbox 2
  • Radio Button - Comma seperated e.g. Radio 1, Radio 2
  • Dropdown - Comma seperated e.g. Option 1, Option 2
  • File - Media upload field

You can set any of your custom fields as required/optional via the checkbox next to each field created.

Files uploaded via a form will be stored within a folder named after the form UID (custom_form_1). You can view these folders via File Manager.

Outputting a Form

You can output forms on any page via Pages in your Admin using Toolbox.

Toolbox compiles the following liquid tag automatically for you when you select a new form to output.

{%- include 'form', id:'custom_form_1', layout: 'default', name: 'test form 1' -%}

Required Parameters:

  • id - The ID of the form you are outputting
  • name - Name of the form you are outputting

Optional Parameters:

  • upload_dir - Formatted example: images/all/ - Default = images/{{id}}/
  • layout - Name of layout you want to use e.g. my-own-layout - Default = default

Editing a Form

You can edit the name, details and fields of any form by clicking on the edit pencil button next to the desired form.

Editing Form Layouts

You can edit the HTML Layout of any form within Code Editor. Form Layouts can be found via layouts/forms/form_name/default.liquid'. You can also create alternate layouts by creating a new.liquid` file within the same folder.

Editing Autoresponders & Workflows

Default fields:

  • {{form.id}} - outputs the ID of the form
  • {{form.properties.name}} - outputs the ID of the form
  • {{form.properties.name}} - outputs the ID of the form

Custom Field Examples:

  • {{form.properties.form_field_3_1}} - outputs the custom field. Update to match the correct field ID
  • {{form.properties.form_field_3_1 | asset_url}} - appends asset_url path to the field contents, this is useful for file field types.

form_field_3_1 - where 3 = form ID and 1 = field ID. You can easily find out the field ID by looking at the default form layout in your Code Editor.

reCAPTCHA

reCAPTCHA is a free service that protects your site from spam and abuse. It uses advanced risk analysis techniques to tell humans and bots apart.

To enable reCAPTCHA on a form, you must first have setup your Integration keys: Integrations.

You can enable reCAPTCHA from the "reCAPTCHA" tab, while editing an existing form. There are two types of captcha available:

v2

Check the checkbox to enable it and select "reCAPTCHA v2" from the drop down. Click save when you're done.

Finally, ensure that you include the following line of code in your form layout: {% spam_protection "recaptcha_v2" %} to display it.

v3

Check the checkbox to enable it and select "reCAPTCHA v3" from the drop down and define your sensitivity score (between 0.0 and 1.0). You can also define an action if you wish. Click save when you're done.

Finally, ensure that you include the following line of code in your form layout: {% spam_protection "recaptcha_v3", action: "signup" %} to display it. If you have not defined an action then remove this from the liquid tag.

Custom Form Validation

Validation occurs when a user clicks submit on a form. There are two types of validation that we’ll outline here as well as providing examples of how you can customise the error messages each provide to your users.

JavaScript Validation

You can use the following line of HTML in your form Form Layout file to output the default JS validation error message:

<div class=“form-error”></div>

A class of .form-error gets added to fields if they fail to validate, which you can write custom CSS to sale as you wish.

You can write your own custom validation by changing:

<button class=“btn buttonAccent” onClick=“s_form_submit_v2(this,’form_12’);”> to be: <button class=“btn buttonAccent” onClick=“s_form_submit_v2(this,’form_12’,error);”>

Here’s an example of custom JS to write your own general error message:

<div id="customErrors"></div> <script> function error(err) { document.querySelector(‘#customErrors’).style.display = ‘block’; document.querySelector(‘#customErrors’).innerHTML = ‘My custom error message’;’ } </script>