Settings

Form Settings

The Canvas AJAX form behaviour is controlled by data-* attributes on the .form-widget wrapper plus a set of reserved hidden fields the PHP processor reads. This guide lists both. The client behaviour lives in the ajaxform.js module.

Wrapper Data Attributes

Canvas reads these attributes from the .form-widget element that wraps the form:

<div class="form-widget" data-alert-type="inline" data-loader="button" data-redirect="thank-you.html" data-timeout="20000">
    <div class="form-result"></div>
    <form action="include/form.php" method="post"> ... </form>
</div>

data-alert-type = how the response is shown. notify (default) renders a floating notification; inline renders the alert inside .form-result as a Bootstrap alert-success / alert-danger.
data-loader = set to button to swap the submit button's label for a spinning icon while the request is in flight. Otherwise the .form-process CSS spinner is shown.
data-redirect = a URL. On a successful (non-error) response the browser is redirected there.
data-timeout = request timeout in milliseconds. Defaults to 30000 (30 seconds).

How Alerts Render

With data-alert-type="inline", the response message is injected into .form-result and slid down as a colored Bootstrap alert:

<div class="form-widget" data-alert-type="inline">
    <div class="form-result"></div>
    <form action="include/form.php" method="post"> ... </form>
</div>

With the default notify, the module sets data-notify-type and data-notify-msg on .form-result and fires the Canvas notifications module to show a toast.

Validation

Canvas validates before submitting. Add .required to mandatory fields and .email to email fields:

<input type="email" name="template-contactform-email" class="required email form-control">

Validation error labels are placed inside the field's .form-group automatically, so wrapping each field in a .form-group column keeps errors positioned correctly.

Custom Submit

If the wrapper has the custom-submit class, Canvas validates the form and then lets the browser submit it normally (a real page POST) instead of doing the AJAX request. Use this when you need the form to post to an third-party endpoint.

<div class="form-widget custom-submit">
    <form action="https://example.com/endpoint" method="post"> ... </form>
</div>

Body State Classes

When the form has an id, the module toggles state classes on <body> through the submit lifecycle, so you can react with CSS or scripts:

<formid>-ready when the form is initialised.
<formid>-processing while submitting.
<formid>-success / <formid>-error on the response.
<formid>-complete once the response is handled.

Reserved Hidden Fields

The PHP processor (include/form.php) treats these submitted field names as configuration, not as email content:

<input type="hidden" name="prefix" value="template-contactform-">
<input type="hidden" name="subject" value="New Contact Request">
<input type="hidden" name="replyto" value="template-contactform-email">
<input type="hidden" name="autoresponder" value="true">

prefix = the string stripped from field names before building the email (so template-contactform-name becomes Name).
subject = the email subject line.
replyto = the field name whose value becomes the mail Reply-To (and the auto-responder recipient).
autoresponder, ar_subject, ar_title, ar_message, ar_footer = auto-responder settings (see the Auto-Responder doc).
template = html (default) or text to control the email body format.
<prefix>botcheck = the honeypot field; must be present and empty.

Options

Summary of the client data-* settings on .form-widget:

data-alert-type = notify (default) or inline.
data-loader = button for an in-button spinner.
data-redirect = success redirect URL.
data-timeout = request timeout in ms (default 30000).
custom-submit class = validate then do a normal (non-AJAX) POST.

Tips

Give the form an id so the <body> state classes fire; this lets you show custom UI on success or error.
Use data-alert-type="inline" when the form sits inside a card and a floating toast would feel disconnected from it.
data-redirect only fires on a non-error response, so failed submissions still show the error in place.
Keep the honeypot field (<prefix>botcheck) empty and hidden with d-none; it is the first line of spam defence before the server checks run.

Settings

Setting	Description
`prefix`	The Prefix that defines the Field's `name` Attribute. Example: `template-contactform`
`subject`	Form Response Email Subject. Example: `New Response from Contact Form`
`template`	Form Response Style. Example: `text or HTML (default)`
`html_title`	Title in the Form Response Email Template. Example: `Form Response`
`replyto`	Use a Email Form Field's `name` Attribute to set a `Reply To:` Header in the Form Response Emails. Also used for Auto-Responders. Example: `template-contactform-email`
`autoresponder`	Enables/Disables Form Auto-Responders. Example: `true, False`
`ar_subject`	Auto-Responder Email Subject. Example: `We've Received your Email`
`ar_title`	Title in the Auto-Responder Email Template. Example: `Thanks for Contacting Us`
`ar_message`	Auto-Responder Message Body. Example: [ch_pre]<input type="hidden" name="ar_message" value="Hello {template-contactform-name},<br><br>Thanks for your Valuable Feed. Here is your Coupon Code: CANVAS30<br><br>You will receive 30% off your Purchase using this Coupon Code.<br><br>See you soon.<br><br>Thanks & Regards,<br><br>Company Team.">[/ch_pre]
`ar_footer`	Auto-Responder Email Template's Footer. Example: `Copyrights © 2019 Company Inc.`
`force_recaptcha`	Enables/Disables Forceful reCaptcha Validation. Example: `true, false`
`message[success]`	Sets a Message that Form returns on Successful Submission
`message[error]`	Sets a Message that Form returns on Error during Submission
`message[error_bot]`	Sets a Message that Form returns on Bot Detection
`message[error_unexpected]`	Sets a Message that Form returns on Unexpected Error. This could be a PHP Error.
`message[recaptcha_invalid]`	Sets a Message that Form returns on Invalid/Expired reCaptcha Validation
`message[recaptcha_error]`	Sets a Message that Form returns on Error in reCaptcha Submission

Was this page helpful?