Form Builder

When you click create new form, you initially start with a blank form. Click on field types to add new fields to your form. Fields include text fields, drop-down boxes, buttons etc. Fields can have dependencies and validations associated with them.

When a form is created and a submission made, Terminalfour creates a corresponding Content Type to manage the content.

To edit or create a new form go to Engage > Forms & Transactions.

Form Listing

Existing forms are listed in the table and can be sorted and filtered by:

• Name
• Last Modified Date
• Usage - the number of instances of this form within Terminalfour
  
  • this can be clicked on to show the number of location of the form instances:

If you are not connected to a Form Bank no forms will be listed and a warning will be displayed on the page.

To edit a form, you can either click on the form name or select Edit from the Actions Menu.

When submissions have been received for a form, they can be viewed from the Submissions option in the Actions Menu.  

Have a look at the documentation on Submissions to learn more.

To delete a form select Actions > Delete.

Create a form

Form creation divides into six steps:

1. General Settings – add necessary form information such as name and description. You can also apply Bootstrap styling or use your own.
2. Fields - select, add and configure form fields. You can also base your form on an existing Content Type
3. Dependencies – optional rules that can show or hide a form field based on the value that is input in another. For example, you might want to hide a list of faculty names unless the respondent ticks a box identifying themselves as a faculty member
4. Submissions – specifies the location that the submissions will be saved to. By default, this is set to an unpublished Section in TERMINALFOUR but a published Section can be specified too. Fields can also be mapped to a Payment Gateway here. In order to use this, a Payment Gateway must already be configured in System settings. You can also customize the redirects (to a URL or TERMINALFOUR Section) and messages for submission success or failure
5. Emails – a copy of each submission can be mailed to one or more Terminalfour Users. Non-Terminalfour user mail addresses can also be added 
6. Finish –  forms can be deployed using:
   • a T4 Tag to add to other Terminalfour content or layouts
   • embed code to add your form to a page not managed by Terminalfour
   • a shareable link that doesn't require a page to be created to deploy it

General settings

Fields

This is where you build your form by adding fields.

Configure field mappings

Map to Content Type

By default, a Content Type is automatically created for each form you create however you can map the Content Elements from an existing Content Type to your form fields.

The quickest way to do this is to select an existing Content Type from the dropdown list and click Create fields from Content Type. A form will be created with fields that map to the Content Elements in that Content Type:

The "Create fields from content type" option is only displayed on new forms that don't already contain form elements. If you have enabled reCAPTCHA on every form, then a form element is added, and you won't see the "Create fields from content type" option.

If you need to change how fields are mapped to the Content Elements, select Configure Field Mapping:

You may notice in the example above that not all Content Elements have been mapped to a field. In this example, one of the elements is a Media File. These do not map to fields. The following field mapping matrix will show you the fields that can and cannot be mapped:

Forms that have incomplete mappings are highlighted with an alert badge in the Existing Form table:

Field / input types

To get started, click on a field type to add it to your form:

Icon	Field type	Description
	Text input	Adds a text input used for text, numbers, passwords, web addresses etc.
	Email input	Adds an email input with an option to allow the user to receive a confirmation of their submission by email
	Dropdown	Allows users to select a single option from a dropdown
	Checkbox	Allows multiple options to be selected from a group
	Radio group	Allows users to select a single option from a group
	Date	Allows users to select a date and optional time
	Date range	Allows a start and end date to be set
	Text area	Allows multiple lines of text to be entered
	WYSIWYG	Displays a WYSIWYG editor to enter HTML. TinyMCE, the WYSIWYG editor that Form Builder uses, follows the WAI specification making it compatible with screen readers.  Find out more about Tiny MCE's Accessibility features.
	File	Uploads a file
	Hidden	Adds an input that will submit a value without the user seeing it
Advanced inputs
	CC info	Adds the required fields to accept payment information from the user. i.e. credit card number, expiry date etc. Only one occurrence allowed per form
	reCAPTCHA	Adds a  to help prevent spam submissions (available from Terminalfour v8.2.10)
Static elements
	Heading	Adds a Heading to the form
	Paragraph	Adds text to the form - useful to explain parts of your form to users
	Line break	Adds a line between fields to divide the form into sections

Field settings

Once added, each field can be edited.

General

Advanced

Validation

Validation can be set for different input data types.

Submit and Reset buttons

Firing a Google Tag Manager Custom Event

When the user clicks the submit button a Google Tag Manager (GTM) custom event named formSubmitted is fired, which also contains the name and description of the form:

{
  'event':'formSubmitted',
  'formName': 'The form name',
  'formDescription': 'The form description'
}

This event can be used in Google Tag Manager so form submissions are tracked.

Dependencies

Dependencies show and hide fields based on the rules you provide.

Dependencies read like a sentence and allow you to show or hide a field based on the value of another one. Click the 'Add dependency' button to get started.

For each dependency, you can have one or more "if" statements and then can show or hide another field based on those conditions.

The operators for the if statements will vary based on the field input type:

• is
• is not
• contains
• does not contain
• is selected
• not selected
• begins with
• ends with
• is populated
• is not populated

From version 8.3.5 the conditions have been simplified so the dependency rule will be triggered:

• "If all" conditions are true (an AND statement)
• "If any" of the conditions are true (an OR statement)

The 'option value' should be entered rather than the 'option text' for any list-based fields.

Submissions

When your form is created you will have to consider what happens to the data when the form is submitted. 

By default, submissions are saved in an unpublished Section, but you can also specify the Section to save submissions to – either a specified Section or a Child of the Section that an instance of the form appears in. You can also send submitted data to a payment gateway.

Submission Statuses

When your form is successfully submitted a new entry is added to the submission database table in Form Bank with a status of "pending". On a failed submission, no entry is added to the database. 

When Form Builder imports the "pending" submissions from Form Bank to Terminalfour, the status of pending entries is changed to "received".

The following two scenarios could result in a failed submission:

• A Password input type with validation (added via the Validation tab) that requires a capital letter. When a form is submitted without a capital letter in the password input value the Form Bank server will throw a validation error that will result in a submission failure message.
• Shutting down Form Bank server right before submitting a form triggers a connection error 

You should always test your form before deploying.

On a successful submission

When a submission is successfully saved the default message displayed to the end-user appears:

The following options can be edited:

On a failed submission

When a submission has failed, the default message displayed to the end-user appears:

The following options can be edited:

Additional Submission Options

Webhook URL

When a form submission is received in Terminalfour, the submission data will be sent to the URL in the Webhook URL field.

Example Payload

Below is an example of a a payload that would be sent in a form submission. 

Payment gateway/credit card fields are ignored and not sent in the webhook request.

{
  "data": {
    "formFields": [
      {
        "Name": "Form test",
        "fieldName": "Name",
        "fieldValue": "Form test"
      },
      {
        "Are you filling surname 1": "Yes",
        "fieldName": "Are you filling surname 1",
        "fieldValue": "Yes"
      },
      {
        "Check any option that apply": "Option 1, Option 3",
        "fieldName": "Check any option that apply",
        "fieldValue": "Option 1, Option 3"
      },
      {
        "Comment": "This is a comment",
        "fieldName": "Comment",
        "fieldValue": "This is a comment"
      },
      {
        "Date with time": "2024-03-27T12:32:00Z",
        "fieldName": "Date with time",
        "fieldValue": "2024-03-27T12:32:00Z"
      },
      {
        "Email": "test@test.com",
        "fieldName": "Email",
        "fieldValue": "test@test.com"
      },
      {
        "Pick a date": "2024-03-28T12:32:00Z",
        "fieldName": "Pick a date",
        "fieldValue": "2024-03-28T12:32:00Z"
      },
      {
        "Select an option": "Option 1",
        "fieldName": "Select an option",
        "fieldValue": "Option 1"
      },
      {
        "Surname1": "This is my surname",
        "fieldName": "Surname1",
        "fieldValue": "This is my surname"
      },
      {
        "Text": "Some text",
        "fieldName": "Text",
        "fieldValue": "Some text"
      },
      {
        "Text (1)": "Some text",
        "fieldName": "Text (1)",
        "fieldValue": "Some text"
      },
      {
        "HTML": "<p>This is an <strong>example</strong>, let's see how is displayed",
        "fieldName": "HTML",
        "fieldValue": "<p>This is an <strong>example</strong>, let's see how is displayed"
      }
    ],
    "formID": 1,
    "formName": "Form test",
    "submissionURL": "http://example.com/form/MS1lbg==",
    "submissionIP": "0:0:0:0:0:0:0:1",
    "submissionTimestamp": "2024-03-15T12:33:29Z"
  },
  "event": "form_submission_add",
  "id": 7,
  "requestType": "Terminalfour Form Submission",
  "timestamp": "2024-03-15T12:34:09.674Z"
}

Error handling

If Terminalfour receives a 200 response from the endpoint you supply the submission we will consider that successfully delivered.

If there is no response, or if we receive an error response, we will retry sending the submission every 10 minutes (be default). After 5 successive timeouts or errors for a given submission we'll display a notification in the main header area of Terminalfour for admins.

Payment gateway field mappings

When a Payment Gateway has been configured and a CC Info field has been added to the form you can select the configured Payment Gateway from a drop-down list.

You can specify values for all submissions here, map them to values submitted in the form, or even calculate them from the values of multiple fields in your form.

Emails

There are two types of emails that can be sent from Form Builder:

• Submission email
  • the emails sent to specified Terminalfour Users or Groups or external (non-system) recipients when the form receives a submission

• Confirmation email
  • this is the email that is sent to the user who has submitted the form (if they have provided their email); it can also contain a copy of their submission

Submission email

The submission mail is sent to specified Terminalfour Users and Groups as well as external mail addresses.

These are the options:

Any files included in a form submission will be attached to the email. In the email itself, the label of the file field will appear with the file name next to it.

If your Terminalfour instance is cloud-hosted with AWS, the submission emails (including attachments) cannot exceed 10MB.

Confirmation email

When a submission is successful, you can select who receives an email with the submission values. Confirmation emails can only be sent from a form that includes an email input field.

To configure the confirmation email:

1. Select Allow a user to receive a copy of their submission in the Confirmation email settings
2. You can customize the Email subject text in the email that's sent
3. By default, this message that appears above the submission text in the confirmation email is "Below is a copy of the information you sent to us". You can change the text by clicking on Customize the confirmation message. This will bring you to the Emails tab, where you can add the custom text.

If you are setting up a new form, the form will be saved before you can customize the text.

Customizing the confirmation message

You can customize the header and footer of the email by clicking on the Customize the confirmation message link and adding the custom header and footer:

The following HTML tags and attributes can be added to the custom header and footer:

When the Allow a user to receive a copy of their submission box is selected, the user will see a checkbox beside the email input:

The confirmation mail looks like this:

Finish

Once you have created and configured your form there are three ways you can configure it:

• T4 Tag
• Embed code
• Shareable link 

Just copy and paste one of the code snippets to deploy your form.

If your form is added with a T4 Tag and contains a WYSIWYG input type you must ensure that the Page Layout that the form is deployed with explicitly has a doctype declaration (<!DOCTYPE html>). If this isn't present, input data will not be saved.

This is because TinyMCE enforces strict standards mode 

Forms added with the embed code or those that use a shareable link are not affected by this.