Forms

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

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.

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

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.

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".
ReCAPTCHAV2 string Using Google's reCAPTCHA V2 to protect forms from spam/non-human submissions.
Upload path A file input allowing users to select a file form 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.

Edit Form Layout

Coming soon...

Form Settings

Coming soon...

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

  • form
    This component outputs data relating to a specific Form. {% component type: "form", alias: "<form_alias>"...
  • Form Submissions
  • {{ formSubmissionData }} object
    This liquid object will output the submission details of a Form. You can use this...
  • {{ workflow }} object
    This liquid object will output the Workflow details of a submitted Form. You can use...
  • {{ order }} object
    This liquid object will output the order details of a submitted Form. Currently, this object...
  • 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.
Send us a message at support@treepl.co and we will consult you as soon as possible.