Email Form

Introduction

Create simple and easily emails from within your templates. Define your own fields, and use the dynamically created variables inside the email template tag.

Nothing fancy in the control panel (expect saving the submissions), just simple building your email, with template inside your template file.

Documentation versions

How it works

The idea of the email form is that you have total freedom of the form markup and how to send the email in an easy way.

First you create a <form> inside the {exp:reinos_email_form:form} tag. Also you can set an email template with the syntax {email_template} inside the template tag {exp:reinos_email_form:form}. As in some situation you only want to send an email template to the admin or to the admin and the user, but differ in text style. With the {email_template} you can create it. So it is normal to end up with 2{email_template} tags.

When a user submit a form, the data that is posted via the form are transferred on the background to the {email_template} tagpair. So if you have a field with the name name="address", the value of address would be converted to the var {address} inside the tagpair {email_template}. Some values are special, like the {to:name}. As you set the to:name="" param on the {email_template to:name="John Doe"} this param will be converted to an variable {to:name} inside the {email_template}.

Installation

Prerequisites

Make sure your system meets the minimum requirements:

Installation Instructions

  1. Upload ee2/system/third_party/email_form to system/expressionengine/third_party/
  2. Install the module in Add-Ons → Modules

Updating

  1. Create a backup of your Database
  2. Run the EE update process

License

For every paid addon you need to validate your license in order to activate the module.

On a local environment, like *.dev *.local *.localhost *.test the license is valid for testing and building a new or existing sites. For every other domain, you need to have a valid license.

Process of validating

Once installed, you will asked to enter your license key. When you entered a valid license you can hit the "Save license" button. This will start validating your license and will redirect you to addons.reinos.nl to login into your account. You can also register a new account in this process.

Control panel overview

Once logged in, you are asked to use your current account or to login with another one.

Control panel overview

Using the current logged in account, the server will check all info related to your license and once valid, it will redirect you back to your site where you see either a success message or an error message.

Control panel overview

License field

This module is using a license field to check if the license for the module is valid or not. On addons.reinos.nl you can check your license and add your valid domains.

Control panel overview

In the Module CP you can enter then your license Control panel overview

When you enter a wrong license, the module will not work and it shows you an warning Control panel overview

Invalid license

Sometimes it happens that the license system says you have an invalid license. When this happens, make sure you have entered your domain url in your account, next to your license on addons.reinos.nl.

If this will not fix your license problem, please contact us on https://addons.reinos.nl/support

Control Panel

Settings

Here you can save the common settings

Submissions

Submissions are saved by default. Here you can manage and explorer them.

Forms

The forms you add in your code can also be saved in the control panel.

Encryption Key

The Email Form use the Encryption class provided by CodeIgniter. In order to work with the Email Form you have to setup a key for the Encryption class first.T

To do that you have to add a config for encryption_key in your config file (ExpressionEngine docs

Example

$config['encryption_key'] = 'sy22k6QK6JzH38u4nLZ65bHOdK6VL89d';

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

return_url="/submission/success"

error_return_url

Specify the url to return on error

error_return_url="/form/error"

required_fields

Set the required field for the form

required_fields="field_1|field|2|field_3"

form_label

Set a label so you can identify you submission in the CP by name

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"

form_id

Set the ID for the form

form_id="submission-form"

secure

Disable/enable the secure function for the forms.

secure="no"

name

If you add a form in the backend, you can select this one here

name=""

email_form_allowed_types

Select the types of files that are allowed to upload.

email_form_allowed_types="gif|jpg|png"

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}

success

The succes message

{success}

validation_errors

Show all validation errors

[EE2]
{validation_errors}

[EE3]
{validation_errors}
    {field} - {error}<br>
{validation_errors}

attachments_error

Show the attachment errors

{attachments_error}

debug

Show the debug message

{debug}

captcha

enable the default EE captcha

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

recaptcha

enable the recaptcha from google

{!-- 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}
lang

Set the correct lang for the reCaptcha

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

lang="en"

Get Form tag

{exp:reinos_email_form:get_form name=''}

Tag Parameters

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

name

The name of the form

name=""

Custom variables

The email_form module whas build because of the use of dynamic variables inside the template which is declared inside your template file and inside the {exp:reinos_email_form:form} tag.

Those variables are simply defined by declaring form fields. See the example page for a real use case.

In cases of an array defined like

<input name="test[]" type="checkbox" value="1"/>
<input name="test[]" type="checkbox" value="2"/>
<input name="test[]" type="checkbox" value="3"/>

This data is available inside your template as (notice the _pair at the end of your variable name)

{test_pair}
    {value}
{/test_pair}

Email template

The email_template is used inside the form tag. This page describes the parameters.

{!-- for inside the form tag --}
{exp:reinos_email_form:form}
    {email_template} ... {/email_template}
{/exp:reinos_email_form:form}

or

{exp:reinos_email_form:email_template} ... {/exp:reinos_email_form:email_template}

Tag Parameters

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

mailtype

Set the mailtype for sending the email.
Options: html text

mailtype="text"

to

Set the recipient email

to="example@example.com"

from:email

Set the From email

from:email="from@example.com"

from:name

Set the From name

from:name="John Doe"

cc

cc receipients, Multiple values seperated by a pipline (|)

cc="test@example.com|test2@example.com"

bcc

bcc receipients, Multiple values seperated by a pipline (|)

bcc="test@example.com|test2@example.com"

subject

Subject for the email

subject="New email"

attachments

Include attachments by field name (pipline seperated for multiple files)

attachments="myfile|myfile_2"

name

To identify the template in the hooks

name="email_template_1"

respect_br

Respect line breaks in HTML mode mailtype="html"

respect_br="no"

direct

When using the tag as a standalone tag, you can set it to direct="yes" so it will send the mail once and display the content on the screen. Great for showing an invoice and send it also directly per mail (once).

With once, we mean just one email. So after a refresh the tag won't send the mail again.

{exp:reinos_email_form:email_template direct="no"} ... {/exp:reinos_email_form:email_template}

Hooks

email_form_send_start

This hook is called right before sending the email. With this hook you can modify the data. (e.g. for in Postmaster)

Added in 1.0

if (ee()->extensions->active_hook('email_form_send_start') === TRUE)
{
    $email_data = ee()->extensions->call('email_form_send_start', $email_data);
}

email_form_send_end

This hook is called right after sending the email.

Added in 1.0

if (ee()->extensions->active_hook('email_form_send_end') === TRUE)
{
    ee()->extensions->call('email_form_send_end', '');
}

email_form_form_start

Added in 1.2

if (ee()->extensions->active_hook('email_form_form_start') === TRUE)
{
    ee()->extensions->call('email_form_form_start', '');
}

email_form_form_end

Added in 1.2

if (ee()->extensions->active_hook('email_form_form_end') === TRUE)
{
    $return = ee()->extensions->call('email_form_form_end', $return);
}

email_form_attachment

assign extra files via an extension. Make sure you return an array with filenames

Added in 1.8

if (ee()->extensions->active_hook('email_form_attachment') === TRUE)
{
    ee()->extensions->call('email_form_attachment', $extra_fields, $vars);
}

Changelog

4.4.1 (29-12-2020)

4.4.0 (02-12-2020)

4.3.0 (24-09-2020)

4.2.0 (20-08-2020)

4.1.1 (10-08-2020)

4.1.0 (09-06-2020)

4.0.2 (17-05-2020)

4.0.1 (29-07-2019)

4.0.0 (27-06-2019)

*Note: There is a change you will have to validate the license again

\Note:** Because the module has been renamed with a prefix reinos_ there is an update path by simply add the new update to your site and install it. By installing the module, you are disabling the old module that can be deleted afterward. Also note that you have to rename the module calls and hooks with a prefix reinos_

See this article about the rename https://addons.reinos.nl/news/modules-renamed

3.3.0 (11-04-2019)

3.2.0 (19-12-2018)

3.1.1 (08-06-2018)

3.1.0 (25-04-2018)

*Note: you need to add your license key and license email from addons.reinos.nl in order to validate your license and add a valid domain url in your license field on addons.reinos.nl/profile/licenses or the module will not work on a live site. Also make sure you have read the license section in the documentation

3.0.0 (04-12-2017)

2.0.4 (01-11-2017)

2.0.3 (01-05-2017)

2.0.1 (21-06-2016)

2.0.0 (20-06-2016)

1.8.1

1.8

1.7

1.6.1

1.6

1.5.4

1.5.3

1.5.2

1.5.1

1.5

1.4.1

1.4

1.3

1.2.1

1.2

1.1

1.0