Forms

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.

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.

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.

reCAPTCHA

reCAPTCHA is an abuse prevention engine powered by Google which can be implemented for website form submissions.

reCAPTCHA v2 or v3 can be selected when building your Treepl CMS form to help protect your CRM from spam/bot submissions that may be attempting to send malicious code to the server or to simply spam your inbox with abusive content and links.

Either reCAPTCHA v2 or v3 is required for all Treepl CMS form submissions (including those with payment collection), with the exception for logged-in users. Forms or payments submitted while a user is logged in to a Secure Zone do not require reCAPTCHA.

Changing from reCAPTCHA v2 to v3

Upgrading from Google’s reCAPTCHA v2 to v3 can be done in just a few easy steps.

First, you’ll need to delete the “reCAPTCHA v2” field from your form builder configuration and add the “reCAPTCHA v3” field.

Then, in your form’s layout, you’ll remove the old code and replace with the new code.

If your form layout has not been modified/saved from the default, Treepl CMS will automatically regenerate the correct form code.

Assuming your form layout has previously been modified in some way, identify the code responsible for rendering the v2 reCaptcha (shown in the image above) and remove it from your form layout. Then, from the “Form Fields” toolbox (at the upper right of the form layout window) you can select the new reCAPTCHA v3 field - which will copy the required code to your clipboard.

Paste this code into your form layout anywhere inside the <form> element (it's location is not critical as it will not be visible in the rendered form).

Optionally, you can restore the whole form layout to default, which will regenerate the new form code. However, this action will also override any customisations you may have done to your form.

Save the form layout and you’re done.

Other considerations may need to be taken into account if you have any customisations in place, such as Javascript/AJAX submission scripts or custom form validation that is expecting the reCAPTCHA v2 elements to be present.

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

Front-End Updating Contacts Logic

How a Contact’s CRM fields are updated after a front-end form submission depends on the Contact’s status in the CRM.

For example; existing stored data against a non-verified Contact can be overridden by subsequent form submissions. However, for verified Contacts (with a ‘member’ status), their data should be protected from unauthorised updates.

Below is a table describing when a Contact’s data is or isn’t updated (based on a front-end form submission that isn’t a Secure Zone registration form):

The logic changes slightly for front-end forms that subscribe Contacts to a Secure Zone (assuming current password entered for those Contact's already Members), as described in the table below:

To update a Contact’s CRM fields, of which has a ‘member’ status, it would be best to use the Update Account Form or the ‘member_update_form’ component.

Related Articles

• Site Settings & Management
  System Pages
  System Pages, under 'Settings', is where you’ll find all those pages required by certain system...
• Reports
  Custom Reports
  Custom reports can be used to bring CRM data together, as a spreadsheet, based on your requirements.
• Liquid Components
  form
  This component outputs data relating to a specific Form. {% component type: "form", alias: "<form_alias>"...
• CRM
  Form Submissions
  Form Submissions store the captured data from any form submission made on your website (from a form created under ‘Content’ > ‘Forms’).
• OpenAPI (Admin)
  CRM Cases API
  Create, Retrieve, Update and Delete CRM Cases via the public API endpoint using "where" filtering.
• Email Notifications
  System Emails
  System emails are emails that are sent when a particular action is carried out on the website and/or via the admin.
• Liquid Objects & Usage
  {{ formSubmissionData }} object
  This liquid object will output the submission details of a Form.
• CRM
  Advanced CRM Groups
  Advanced CRM Groups allow you to extend the data fields within multiple areas of the CRM, either globally or on a per-record basis.
• Liquid Objects & Usage
  {{ workflow }} object
  This liquid object will output the Workflow details of a submitted Form. You can use...
• Liquid Objects & Usage
  {{ order }} object
  This liquid object will output the order details of a submitted payment. {{ this.order }}...
• Content Modules
  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.
• OpenAPI (Admin)
  Forms API
  Retrieve Forms via the public API endpoint using "where" filtering.
• eCommerce
  Payment Form Javascript
  Options for controlling and further customising payment form submissions are available via javascript events.
• Extras
  ReCaptcha Styling
  Treepl CMS supports Google reCAPTCHA v2 and v3 implementations. Below are some additional options you...

External Resources

• Standard Form example
• Basic AJAX Form submission example
• Accepting an Arbitrary Price via Payment Forms

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.