Addons by Reinos

Appearance

Tag ​

{exp:reinos_email_form:form}

Tag Parameters ​

Below are the Tag Parameters. Those parameters can be used in the tag described above

return_url ​

Specify the url to return after submission. Defaults to the current page.

return_url="/submission/success"

error_return_url ​

Specify the url to return on error. Defaults to the current page.

This is used for every error: CSRF, honeypot, minimum submit time, rate limit, validation, captcha, reCAPTCHA/Turnstile and uploads, and the errors while sending (the email could not be sent, a duplicate email address or a to:field without a recipient). The submitted values are kept, see field_name:value.

error_return_url="/form/error"

required_fields ​

Set the required field for the form. The error is "This field is required.". From v6.0.0 a field that is not posted at all (e.g. an unchecked checkbox) also fails.

required_fields="field_1|field_2|field_3"

rules:field_name ​

Available from v6.0.0

Validate a field with the ExpressionEngine validation rules, separated by a pipe. The errors are shown via {field_name:error} (the first error of the field) and {validation_errors}, with the messages of ExpressionEngine (e.g. "This field does not match the email field.").

A rule on an empty field passes, unless the field is also required. An unknown rule stops the submission with the {error} "The form could not be processed, please reload the page and try again" and an error in the log.

rules:email="required|email"
rules:phone="numeric|minLength[10]"
rules:email_confirm="matches[email]"

form_label ​

Set a label so you can identify your submission in the CP by name. Defaults to default.

form_label="Contact form"

form_class ​

Set the class of the form

form_class="submission-form"

form_attr:your-attr ​

Set a custom form attr

form_attr:novalidate="true"

Common attributes such as novalidate, autocomplete, style, title, data-* and aria-* can also be set as normal tag parameters, ExpressionEngine adds them to the <form>. target is not passed on that way, use form_attr:target="_blank":

{exp:reinos_email_form:form novalidate="novalidate" data-type="contact"}

From v6.0.0 the form only gets enctype="multipart/form-data" when it contains a file input (<input type="file">). When the file input is not in the form tag itself, e.g. in an {embed} or added with JavaScript, it has to be set with form_attr:enctype="multipart/form-data".

form_id ​

Set the ID for the form. Defaults to email-form.

form_id="submission-form"

allowed_types ​

Select the types of files that are allowed to upload. Defaults to gif|jpg|png|pdf, or the email_form_allowed_types config override. The old email_form_allowed_types tag parameter still works as well.

allowed_types="gif|jpg|png"

INFO

The old current_url parameter has no effect: the form always sends the visitor to the return_url or error_return_url.
The old secure parameter has no effect anymore, use the CSRF protection setting in the Control Panel instead.
To show a form that is saved in the control panel, use the get_form tag.

Tag Variable ​

Below are the Tag Variables. Those Variables can be used in the tag described above

email_template ​

Inside this tagpair you can build your own template, instead of using the default templates defined inside the control panel.

More information here

{email_template}
  This email is sent to {to:name} with the following message: <br />
{body}
{/email_template}

field_name:value ​

The submitted value of a field, so the form is filled in again after an error. Replace field_name with the name of your field. The values are cleared after a successful submit.

From v6.0.0 the value is HTML-escaped and kept after every error (validation, captcha, reCAPTCHA, honeypot and upload).

<input type="text" name="email" value="{email:value}" />

field_name:error ​

The validation error of a field from required_fields or rules:field_name

{email:error}

success ​

The success message: "The email has been sent". It is not set when no email was sent (send_email="no", or a direct email that was already sent).

{success}

// or use it to show a custom message
{if success}Your custom message{/if}

error ​

The error message, e.g.:

  • "The email could not be sent", also when a to:field value has no recipient
  • "This email address has already been used for this form" (allow_duplicate_email_address="no")
  • "Too many submissions, please try again later" (Rate limit)
  • "The form was submitted too fast, please try again" (Minimum submit time)
  • "The form has expired, please reload the page and try again" (CSRF protection)
  • "The form could not be processed, please reload the page and try again" (an unknown validation rule)

See error_return_url for the page the visitor is sent to.

{error}

// or use it to show a custom message
{if error}Your error custom message{/if}

validation_errors ​

Show all validation errors

{validation_errors}
	{field} - {error}<br>
{/validation_errors}

attachments_error ​

Show the attachment errors: the upload error of ExpressionEngine in a <p>, or "The attachments could not be uploaded, please try again later" when the upload folder cannot be created.

{attachments_error}

honeypot_error ​

The error when the honeypot field is filled in, see the Honeypot setting in the Control Panel

{honeypot_error}

Duplicate email error ​

This error is generated when you use allow_duplicate_email_address="no" and a user fills in the form twice. {error} holds the message as well.

{if error_duplicate_email}Already send the email{/if}

captcha ​

The default EE captcha. It is only shown when the Require CAPTCHA setting of ExpressionEngine is enabled, and for logged in members only when Require CAPTCHA while logged in is enabled as well; otherwise the {if captcha} block is removed. A captcha word can be used once and expires after 2 hours.

{if captcha}
    <span style="color:red;">{captcha_error}</span><br>
    {captcha}<br /> 
    <input type="text" name="captcha" value="" maxlength="20" />
{/if}

recaptcha ​

Shows the captcha that is selected in the Control Panel: Google reCAPTCHA or (from v6.0.0) Cloudflare Turnstile. {recaptcha_error} holds the error when the captcha check failed, e.g. "You did not check the reCAPTCHA", "Looks like you are a bot." or "The captcha could not be verified, please try again".

{!-- init tag should be placed in the head --}
{exp:reinos_email_form:init_recaptcha}

{if recaptcha}
    <span style="color:red;">{recaptcha_error}</span><br>
    {recaptcha}
{/if}

init_recaptcha tag ​

Loads the scripts of the selected captcha, place it in the head of your page.

{exp:reinos_email_form:init_recaptcha lang="en"}

lang ​

The language of the reCAPTCHA widget, defaults to en. Not used for Turnstile, which detects the language of the visitor.

See the full list of languages here https://developers.google.com/recaptcha/docs/language

lang="en"

Ajax ​

Available from v6.0.0

Submit the form with JavaScript and send an Accept: application/json header (or X-Requested-With: XMLHttpRequest). The add-on then returns JSON instead of a redirect, with status 200 on success and 422 on an error:

json
{
    "success": false,
    "message": "This field is required.",
    "errors": {},
    "field_errors": {"email": "This field is required."}
}

On success:

json
{"success": true, "message": "The email has been sent", "errors": {}, "field_errors": {}}

errors holds the other errors, e.g. captcha_error, recaptcha_error, attachments_error, honeypot_error, error_duplicate_email or error. field_errors has one message per field; validation_errors is not in the JSON. message is errors.error when set, otherwise the first other error or field error. When no email was sent (send_email="no", or a direct email that was already sent), message is "The form has been submitted".

When the form data is missing or cannot be decrypted (e.g. after the encryption key changed), the JSON has success: false and the error "The form could not be processed, please reload the page and try again".

html
<script>
document.querySelector('#email-form').addEventListener('submit', async (event) => {
    event.preventDefault();

    const response = await fetch(event.target.action, {
        method: 'POST',
        body: new FormData(event.target),
        headers: {'Accept': 'application/json'},
    });
    const result = await response.json();

    alert(result.message);
});
</script>

The invisible captchas set their token before your submit handler runs, so {exp:reinos_email_form:init_recaptcha} works with ajax as well, also when the form is submitted again. The reCAPTCHA checkbox and the Turnstile widget are not reset after an ajax submit; reset them in your own script.