Change log

Forms

Forms are an essential part of collecting user information on your website.
Treepl CMS makes managing forms easy and powerful

0

Quick Start

Creating a Form

Found under 'Content' > 'Forms' in the admin, you can create as many forms as needed, add system and custom fields, edit the forms HTML layout and configure advanced settings such as notifications and Form behaviour.

Forms - Create / Edit

To create a new form click the blue 'ADD NEW FORM' button at the top of the page, or to edit an existing form click on the form name or the associated pencil icon on the far right.

1
Form Builder

When creating or editing a form you'll be able to set the name, alias and type of the form and build out the desired fields using the form builder.

Name
Description
Name
Descriptive name for the form.
Form Alias
System reference for the form.

Changing the alias will result in any existing references to the previous Form alias breaking.

Type

Generic
If payments are collected via the form, this option configures the form for general collection of any arbitrary amount.

SingleItem
If payments are collected via the form, this option configures the form for collection of payment against Event or Module items that have a price.

CheckOut
If payments are collected via the form, this option configures the form for use in the shop checkout process, collecting the order total.

Simply click on the system field button on the left to add them to your form preview on the right.
You can also create custom fields of various data types by clicking the '+ Add custom field' link under the system field button.

By dragging the form preview fields around you can rearrange the order they will be output in the default HTML form layout.
Fields added to your form preview can also be further edited by hovering over the field and clicking the pencil icon.
Likewise, clicking the trashcan icon will remove the field from your form configuration.

Field options vary depending on the data type chosen, however most fields can also be set to "required", which will enforce those fields to be completed before a successful submission can be made.

Make sure you save both the field you are working on AND the whole form itself (with the save button at the bottom of the page) to ensure all changes are applied.

reCAPTCHA v2 or v3 is required on all forms unless they include payment fields or are submitted via a logged in user.

System Fields

Name
Description
Email
Field to accept users email address into the CRM.
First Name
Field to accept users first name into the CRM.
Last Name
Field to accept users last name into the CRM.
Phone
Field to accept users phone number into the CRM.
Site
Field to accept users website address into the CRM.
Address
Field to accept users address line (unit/number and street) into the CRM.
City
Field to accept users city/suburb/provence into the CRM.
State
Field to accept users state/territory into the CRM.
ZipCode
Field to accept users zipcode/postcode into the CRM.
Country
Field to accept users country into the CRM (will accept any string value; country name, country code or otherwise)
Status
Field to accept an arbitary value into the CRM to assign any particular status to a user.
Notes
Field to accept an arbitary value into the CRM to assign any particular notes to a user.
Mailing Lists
When an Email Marketing provider is enabled for your site and Mailing Lists have been created, they will be listed for this form field option where you can select which mailing list/s the user will be subscribed to.
Accept Payment
Adds payment related fields to the form, including a dropdown to select payment method (based on payment gateway/s enabled) and an amount field.
The amount field is expecting a value set via a custom property in the form's component tag, eg: {% component type: 'form', alias: '<form_alias>', price: '9.95' %}
Or otherwise passed as a Liquid variable called paymentAmount (as is the case when used in conjunction with a paid Event).
Accept Event Subscription
Adds Event related fields and Liquid data to the form, including the appropriate Event component tag and an allocations (seats) field.
The form is expecting an Event ID to be provided via a custom property in the form's component tag, eg: {% component type: 'form', alias: '<registration_form_alias>', eventId: '{{this['id']}}' %}

This assumes the Event form is placed on the Event detail layout, where {{this['id']}} will work. Otherwise, the Event ID will need to be hard-coded manually or added via an alternative Liquid variable.

Password
Adds a password field and corresponding confirm password field, which needs to match for a successful form submission. Password will be assigned to the user in the CRM.
Secure Zone Expiry Date
Adds a date field which will assign the provided date as the users Secure Zone Expiry Date.

Cannot be combined with below Secure Zone Expiry Duration

Secure Zone Expiry Duration
Adds a number field which will assign the provided value as the users Secure Zone Expiry Days.

Cannot be combined with above Secure Zone Expiry Date

reCAPTCHA v2
Adds Google reCAPTCHA v2 spam protection to the form.

Cannot be combined with below reCAPTURE v3

reCAPTCHA v3
Adds Google reCAPTCHA v3 spam protection to the form.

Cannot be combined with above reCAPTURE v2

Field Types

Type
Data
Description
DateTime
string
This field will accept any string as it's value.
Although, may want to use a standard date format (such as ISO 8601) or implement a date picker plugin to correctly format a date so you can better use that data later in your code.
CheckboxList
comma-separated list
Allow multiple options to be selected from a list of available options as checkboxes.
DropdownList
comma-separated list
Allow a single option to be selected from a dropdown list of available options.
ListboxList
comma-separated list
Allow multiple options to be selected from a list of available options.
RadioList
comma-separated list
Allow a single option to be selected from a list of available options as radio buttons.
Multiline
string
Multiline inputs allow larger amounts of text to be entered along with line breaks.
String
string
String inputs allow for a single line of text.
Boolean
true/false
Booleans allow only a true of false selection. When not selected its submitted value will be blank and when selected its value is 'on'.
Upload
path
A file input allowing users to select a file from their computer to upload.

If using the Upload field type you must add enctype='multipart/form-data' as an attribute to your form element.

Upon successful upload the file will be listed in the CRM under 'Form Submissions' and the file will be stored on the server using a directory structure in the following format:
/_form_submissions/<form_id>/<submission_id>/<file_name.ext>-<dateStamp>

The multiple parameter is currently not supported for file type inputs. To add multiple file upload fields to your form you will need to add additional upload fields in the Form Builder and insert the corresponding HTML into your form layout.

2
Edit Layout

Upon first creation of a Form, the Layout will auto-generate the default Form code that will be used to render your fully functioning Form to the page.
Whilst this default Form Layout has not been edited it will continue to auto-update if any fields are added or edited.
If however, your Form Layout has been customised, you will need to manually adjust it for any fields added or modified in the Form Builder.

To get the correct form field code for any system or custom field added via the Form Builder, click the “Form Fields” button and select the desired field from the list. Doing this will copy the field code to your clipboard ready for pasting into the Layout.

The Form Layout can also be reset back to default by clicking the “Restore to Default” button.

This will remove any custom code changes made in this Layout.

3
Settings

Form Settings allow you to control aspects of the Forms behaviour after it is submitted, such as the Workflow triggered, Secure Zone subscription process and Auto-responder settings.

Option
Description
Workflow

Assign the Workflow/s to be triggered upon successful form submission.

You can also programatically trigger Workflow Notifications - see below for details.

Secure Zone

Subscribe the user to a Secure Zone/s upon successful form submission.

This setting will redirect the user to the Secure Zone's landing page after successful form submission (unless a custom redirect is enabled - see below for details) and will also trigger the 'Secure Zone Login Details' System Email to be sent to the user.

Enable Secure Uploads

Enables restricted access to any files in the designated upload folder (assigned in the ‘Uploads Folder’ setting below). Access to the files will only be granted for logged in admin users, else, the 403 - Forbidden system page will be shown.

Uploads Folder

Assign a folder to be used for this form’s file uploads (if any ‘Upload’ field types are used). Default folder path is ‘/_form_submissions/’. If the folder does not exist at time of form submission the folder will be created.

Auto-response

The auto-response is an email sent out to the user after the Form has been submitted from the front-end of the website.

Option
Description
Enable
Enable the auto-response email to be sent.
Template
The Email Template to be used for the auto-response email.
From Name

The display name used for the email sender.

This field supports Liquid which can be used to insert dynamic content such as member details, form submission details or even data from other modules.

From Email
The email address used for the email sender and reply address.
Subject

The subject line used for the auto-response email.

This field supports Liquid which can be used to insert dynamic content such as member details, form submission details or even data from other modules.

Body

The content of your auto-response email.

This field supports Liquid which can be used to insert dynamic content such as member details, form submission details or even data from other modules.

Redirecting Forms to a Custom Confirmation Page

By default, form submissions will direct users to the /_form-submission-results/ system page. However, you can override this behaviour and redirect users to any other page you require.

To do this, you can add a hidden form input with name redirectURL and set it's value to the new page URL:
(If this input is included in the form and it's value is empty it will continue to redirect to the default confirmation page.)

<input type="hidden" name="redirectURL" value="/my-new-confirmation-page">

Triggering Different Workflows

A form can be configured, via its ‘Settings’ tab, to trigger single, or multiple, predefined Workflows. However, there may be cases where you want to trigger a different Workflow/s based on conditions during the form's submission on the website.

An example of this might be allowing the user to select which department an enquiry is to be sent to. Or perhaps the condition is dynamically set, without user input, based on other variables such as Liquid data or detecting a users selection of another input via Javascript.

You can achieve this by adding an input to the form with name="customWorkflows" and value="[WorkflowID]" where [WorkflowID] is to be replaced with your desired workflow’s ID.

You can find the Workflow ID by navigating to the appropriate Workflow in the Treepl CMS Admin and noting the trailing number in the URL.
eg: https://[YOURSITE]/admin/custom-workflow/2

Insure your site plan supports multiple Workflows in order to utilise this method.

In the first example, where the user can select the appropriate workflow, you could add a dropdown to the form with the following values:

<select name="customWorkflows">
    <option value="[WorkflowID]">Sales Enquiry</option>
    <option value="[WorkflowID]">Technical Support</option>
</select>

Or the second example, where the Workflow is set based on other conditions such as a Liquid variable, you could have a hidden input field like so:

<input type="hidden" name="customWorkflows" value="{{myWorkflowVariable}}">

Or, if setting the Workflow ID with Javascript based on the selection made in another dropdown:

<input type="hidden" name="customWorkflows" value="1">

<select name="enquiryType">
    <option value="">- Please select -</option>
    <option value="Sales Enquiry" data-workflowid="1">Sales Enquiry</option>
    <option value="Technical Support" data-workflowid="2">Technical Support</option>
</select>
<script>
    var workflow = document.querySelector('input[name="customWorkflows"]');
    var selector = document.querySelector('select[name="enquiryType"]');
    
    selector.addEventListener('change', changeWorkflow);
    
    function changeWorkflow(el) {
        var dataID = el.target.options[el.target.options.selectedIndex].getAttribute('data-workflowid');
        workflow.value = dataID;
    }
</script>

You can even trigger multiple Workflows by changing the input type to a multi-selection style input, such as checkboxes:

<input type="checkbox" name="customWorkflows" value="1">
<input type="checkbox" name="customWorkflows" value="2">

Or even with a comma separated list of Workflow ID’s in a text input.

<input type="text" name="customWorkflows" value="1,2">

Triggering Workflows based on form inputs, with either a valid or invalid value for the Workflow ID, will override any Workflow settings configured in the forms ‘Settings’ tab, even if no Workflow is enabled there.

JSON Response & AJAX Form Submission

The form supports jsonResponse=1 as a parameter in the form's action attribute.

You can then render the JSON response using the formSubmissionData object or use it to handle the form submission via AJAX (see Related Articles and External Resources below for more details).

<form action="/forms/cases.ashx?form=my_form&jsonResponse=1" method="post">


Related Articles

  • System Pages
    System Pages, under 'Settings', is where you’ll find all those pages required by certain system...
  • Custom Reports
  • form
    This component outputs data relating to a specific Form. {% capture data %} {% raw...
  • Form Submissions
  • System Emails
    System emails are emails that are sent when a particular action is carried out on the website and/or via the admin.
  • {{ formSubmissionData }} object
    This liquid object will output the submission details of a Form.
  • {{ workflow }} object
    This liquid object will output the Workflow details of a submitted Form. You can use...
  • Advanced CRM Groups
  • {{ order }} object
    This liquid object will output the order details of a submitted payment. {% capture data...
  • Secure Zones
    Secure Zones provide a way of creating restricted content on your website that only registered Secure Zone Members are able to access after successfully logging in.
  • ReCaptcha Styling
    Treepl CMS supports Google reCAPTCHA v2 and v3 implementations. Below are some additional options you...

External Resources


Please let us know if you have any other contributions or know of any helpful resources you'd like to see added here.


Questions?

We are always happy to help with any questions you may have.
Visit the Treepl Forum for community support and to search previously asked questions or send us a message at support@treepl.co and we will consult you as soon as possible.