Contact Plugin

The contact plugin allows you to easily customize and display a form that sends an email upon submission. You can create text, textarea, file, hidden, and dropdown fields in your form, and customize the email content.

{{ contact:form }}

Setting Up Fields

You can customize which fields you want by creating a parameter with the desired name of your field, followed by some data about that field. Each piece of data is separated by a pipe character (|). Along with some special values, you can specify form validation rules (available validation rules are listed below).

Your field will be available to display as a variable between the form tag pair. So, for insance, if you want to create a required text field called "name", you can add this as a parameter:

name="text|required"

You can now display this input field with a variable:

{{ name }}

Available Field Types

The following field types are available to be used with the contact form. (Not to be confused with Streams field types, which are separate and for use with streams, not the contact form).

Text

A simple text input.

name="text|required"

Textarea

The same as text above, but a textarea.

name="textarea|required|alpha_numeric"

Hidden

A hidden input. Takes the name of the hidden element should appear in the 2nd space with an equals sign in front of it.

name="hidden|=my_value|required"

File

A file upload input. Since required is the only real validation rule that can be applied to a file input, you can specify the file types allowed with the input:

attachment="file|required|jpg|png|gif"

You can also opt to not require the file input:

attachment="file|pdf|doc"

File attachments will automatically be put into a folder called 'contact_attachments' in your file upload folder. If it doesn't exist, it will be created.

Dropdown

Creates a select dropdown element. Since required is the only real validation rule that can be applied to a dropdown, the rest are each of the dropdown values that you want in a key=value or just value format:

best_time_to_call="dropdown|required|Morning|Afternoon|Evening|Night"

If you want to specify keys, you can:

subject="dropdown|required|support=Support Request|compliment=Compliment"

Available Field Validation Rules

The following rules are available, and are reproduced here from the CodeIgniter validation rules.

Rule	Description	Example
required	Returns `false` if the form element is empty.
matches	Returns `false` if the form element does not match the one in the parameter.	matches[form_item]
min_length	Returns `false` if the form element is shorter then the parameter value.	min_length[6]
max_length	Returns `false` if the form element is longer then the parameter value.	max_length[12]
exact_length	Returns `false` if the form element is not exactly the parameter value.	exact_length[8]
greater_than	Returns `false` if the form element is less than the parameter value or not numeric.	greater_than[8]
less_than	Returns `false` if the form element is greater than the parameter value or not numeric.	less_than[8]
alpha	Returns `false` if the form element contains anything other than alphabetical characters.
alpha_numeric	Returns `false` if the form element contains anything other than alpha-numeric characters.
alpha_dash	Returns `false` if the form element contains anything other than alpha-numeric characters, underscores or dashes.
numeric	Returns `false` if the form element contains anything other than numeric characters.
integer	Returns `false` if the form element contains anything other than an integer.
decimal	Returns `false` if the form element is not exactly the parameter value.
is_natural	Returns `false` if the form element contains anything other than a natural number: 0, 1, 2, 3, etc.
is_natural_no_zero	Returns `false` if the form element contains anything other than a natural number, but not zero: 1, 2, 3, etc.
valid_email	Returns `false` if the form element does not contain a valid email address.
valid_emails	Returns `false` if any value provided in a comma separated list is not a valid email.
valid_ip	Returns `false` if the supplied IP is not valid. Accepts an optional parameter of "IPv4" or "IPv6" to specify an IP format.
valid_base64	Returns `false` if the supplied string contains anything other than valid Base64 characters.

Creating an Email Template

If you would like to send an email using a template, you can do so by editing the default contact template or creating your own. To see how to create your own email templates, please see the documentation on the email template module.

The contact form comes with a basic contact email template already set up, which you can edit in the email template module and is set as the default for the template form parameter. The following fields are available for use:

Name	Description
sender_agent	The form submitter's browser name and version.
sender_ip	The form submitter's IP address.
slug	The template slug.
reply-to	The email reply to address.
to	The value in the 'to' field for this email.
from	The value in the 'from' field for this email.
reply-to	The email reply to address.

We also have access to all of the fields we put in the contact form in the email template. Attachments will be automatically attached to the email.

Example Email Template:

This message was sent via the contact form on with the following details:

IP Address: {{ sender_ip }}
OS: {{ sender_os }}
Agent: {{ sender_agent }}

{{ message }}
{{ name }},
{{ email }}

Form Attributes

The following attributes can be used to customize your form. None of these attributes are required.

Name	Default	Description
max-size	None	The size in kb of file attachments to allow.
reply-to	None	The email address to use for the reply to field. If a form input named 'email' is found and you have not specified a reply-to address, the 'email' input will be used.
button	Send	The text to display on the submit button. Defaults to 'Send'. The first letter in the button will always be capitalized.
template	contact	Email template slug to use for sending the contact email.
lang	en	Email template language version to use for this instance of the contact form.
to	Site Contact Email	The email address to send to.
from	Site Server Email	This address will show as the "from" email address.
sent	Translated string found in lang file	This message is shown to the user after they have sent a message. Use this to set a custom message.
error	Translated string found in lang file	Set a custom error message here. It will display if there is a server error when sending the email.
success-redirect	Current Page	Set url segments here if you want the user to be sent to a different page after a successful send.
auto-reply	None	If you provide a valid email template slug here it will be used to send an automatic reply email to the user that submitted the form. The same data is available in the auto-reply template as in the regular contact template. This is useful if you want to send the user an email message along the lines of "thank for you filling out this form". Make sure to include an input called 'email' - this is where the email will be sent.

Examples

{{ contact:form
    name = "text|required"
    email = "text|required|valid_email"
    subject = "dropdown|required|hello=Say Hello|support=Support Request|Something Else"
    message = "textarea|required"
    attachment = "file|jpg|png|zip"
}}
    {{ name }}
    {{ email }}
    {{ subject }}
    {{ message }}
    {{ attachment }}
{{ /contact:form }}

Advanced Example

{{ contact:form
    name = "text|required"
    email = "text|required|valid_email"
    subject = "dropdown|required|hello=Say Hello|support=Support Request|Something Else"
    message = "textarea|required"
    attachment = "file|jpg|png|zip"
    max_size = "10000"
    reply-to = "visitor@somewhere.com" * Read note below *
    button = "send"
    template = "contact"
    lang = "en"
    to = "contact@site.com"
    from = "server@site.com"
    sent = "Your message has been sent. Thank you for contacting us"
    error = "Sorry. Your message could not be sent. Please call us at 123-456-7890"
    success-redirect = "home"
}}
    {{ name }}
    {{ email }}
    {{ subject }}
    {{ message }}
    {{ attachment }}
{{ /contact:form }}

If there is an "email" field in the form, it will be used for the reply-to address. Your form should have a reply-to address set or else contain an "email" field in the form.