Awesome Contact Form

Welcome to the user guide, and thank you for purchasing the Awesome Contact Form! This user guide will help you set up your contact form and integrate it into your website. It will also show you how to extend the contact form by adding your own fields.

File Structure
Installation
Upgrading
Configuration
Editing the Form
Managing Fields
1. Adding Fields
2. Field Validation
Example Fields
1. Text
2. Textarea
3. Select
4. Checkbox
5. Radio Buttons
Custom Error Messages
Multiple Forms
Handling Form Data
Help and Support
Credits

File Structure

It is recommended that you keep all the script files inside the includes directory and reference them from outside. For example:

index.php (Site Homepage)
about.php (About page)
contact_me.php (Contact Me page)
includes/
- assets/ (Image folder)
- contact.php (Contact script)
- form.php (Form layout)
- captcha.php (Image verification script)

Installation

Installing the Awesome Contact Form is easy. First, upload all the files in the code folder to your web server. Then, open the file which you would like to add the contact form to. (Note that this code must be placed on a .php page, however this can usually just involve renaming the file extension.) Add the following snippet of code to the beginning of the page (before the <html> tag:

<?php include('includes/contact.php'); ?>

Then, add the following piece of code where you want the form to go.

<?php $form->displayForm(); ?>

That's it! The form should now show on your site, but you will need to configure it a little first. It is suggested you take a quick look through the documented configuration options below, and you can make any changes in the includes/config.php file.

It is recommended you keep the default file structure to avoid any need to change the paths inside non-configuration files.

Upgrading

Upgrading from v1.2

It's easy to upgrade from Version 1.2 to v1.3:

Backup your existing files. (just in case)
Replace your existing contact.php with the updated version from the code/ folder.

Version 1.3 brings a new feature to the script:

You can now pass data from the contact form to another script using session variables.
A new configuration option has been added:
- $config['save_session']

Upgrading from v1.1

There are minimal differences between Version 1.1 and Version 1.2:

Backup your existing files. (just in case)
Replace your existing contact.php with the updated version from the code/ folder.
If you are using the example files, replace example/assets/sample.css with the updated version from the example/assets/ folder, and example/contact_us.php with the updated version from the example/ folder.

Upgrading from v1.0

There are only a few slight differences between v1.0 and v1.1. To update your Contact Form, follow these steps:

Backup your existing files. (just in case)
Replace your existing contact.php with the updated version from the code/ folder.
Replace your existing captcha.php with the updated version from the code/ folder.

Version 1.1 makes the script compatible with PHP4, as well as adding some new features:

You can now run multiple forms from one installation of the script.
Three additional (and optional) configuration options added:
$this->value() has been extended to support conditional outputs - see the section on select menus, checkboxes and radio buttons.
The image verification has been rewritten and combined with the core class.

Configuration

The Awesome Contact Form comes with tons of configurable options, so that you can get the most out of the script without having to touch the main class. These options can be found in the includes/config.php file, and an explanation about each option, what it does, and a brief example, is explained below.

Editing the configuration file is simple. It is recommended you backup the file before making changes, just in case, and remember to use PHP syntax when editing - so semicolons need to be at the end of each statement of PHP and all strings need to be enclosed in quotes. If you're not sure, then check out the php.net user guide.

$config['address']

This config setting is the email address in which all emails should be sent to.

$config['address'] = 'test@test.com';

$config['subject']

This config setting is the subject line set in all emails sent from the form. You can use any field name sent through the form (e.g. name/email/subject) by encasing it with double square-brackets:

$config['subject'] = '[[name]] has sent you a message - [[subject]]';

$config['body']

This config setting controls the body of the email sent from the form. By default it will include the name, email, subject and message, but if you choose to add your own fields then you might want to edit this to include them. Like $config['subject'], it can contain field names sent through the form.

$config['body'] = "[[name]] has sent you a message from [[email]] with the subject [[subject]].\n\n[[content]]";

$config['raw']

This config setting, when set to TRUE, will add a section to the end of the email sent by the form which lists all the validated fields and their values. This is useful if you have multiple fields (e.g. telephone/country/website) but don't want to write them all into $config['body'].

$config['raw'] = TRUE;

$config['sender_copy']

This config setting, when set to TRUE, will send an automatic email to the sender when the form is submitted. You can specify the subject, body and from address in subsequent config variables.

$config['sender_copy'] = TRUE;

$config['sender_email']

This config setting sets the email address which the automatic email to the sender appears to originate from. The email address does not have to exist. This setting is only used if $config['sender_copy'] is set to TRUE.

$config['sender_email'] = 'noreply@test.com';

$config['sender_subject']

This config setting sets the subject of the automatic email to the sender. Like $config['subject'], it can contain field names sent through the form. This setting is only used if $config['sender_copy'] is set to TRUE.

$config['sender_subject'] = 'Thanks, [[name]], for your email!';

$config['sender_body']

This config setting sets the body of the automatic email to the sender. Like $config['subject'], it can contain field names sent through the form. This setting is only used if $config['sender_copy'] is set to TRUE.

$config['sender_body'] = "Hi [[name]],\n\nThanks for your email. I will get back in touch with you shortly.";

$config['success_page']

If this config variable is set, the script will automatically redirect users to the specified page when the form is successfully completed. If the config value is FALSE or empty, the users will be shown the success message specified in $config['success_message'] instead.

$config['success_page'] = 'http://www.company.com/success.html';

$config['success_message']

If $config['success_page'] is empty, the script will show this message when the form is successfully completed.

$config['success_message'] = 'Thanks for your message!';

$config['fields']

This config variable is an associative array which tells the script which fields to check for. You can also set validation rules and requirements on each field. See Adding Fields for more information about this.

$config['fields']['telephone'] = array('type' => 'number', 'length' => 11, 'required' => true);

$config['email_field']

By default, the name of the field which is used for the sender email address is called 'email' (case-sensitive). However, if you want to use a different field (eg. 'sender'), set the name of the field as the value.

$config['email_field'] = 'sender';

$config['use_captcha']

When set to TRUE, this config variable will enable the CAPTCHA image verification on the form. This means that the user will have to enter characters from an image to confirm that they are not a bot. This is an effective spam prevention measure.

$config['use_captcha'] = TRUE;

$config['captcha_path']

When $config['use_captcha'] is enabled, this config value needs to point to the relative path of the CAPTCHA script (includes/captcha.php) from wherever the form is being called from.

$config['captcha_path'] = 'includes/captcha.php';

$config['captcha_base']

When $config['use_captcha'] is enabled, this config value needs to point to the relative path of the CAPTCHA base image (includes/assets/captcha.png) from the location of the captcha script.

$config['captcha_path'] = 'assets/captcha.png';

$config['use_check']

When $config['use_captcha'] is disabled, this config value, if set to TRUE, will use a human security question to check if the user is a bot. A simple mathematical question will be used.

$config['use_check'] = TRUE;

$config['identifier']

When using multiple forms on the same domain, it's recommended that you set a different identifier for each form to avoid session issues. You can use any alpha-numeric characters in your identifier, along with dashes and underscores. If you're only using one instance of the form, you can ignore this.

$config['identifier'] = 'contact-me-form-1';

$config['save_session']

If you want to pass data between the contact form and another script, you can set this to TRUE. This will save the contact form data to a PHP session variable.

$config['save_session'] = TRUE;

$config['show_errors']

By default, errors generated while the email is being sent are hidden. This is recommended for a live site. However if you encounter problems sending emails, set this to TRUE and any errors will be displayed.

$config['show_errors'] = TRUE;

$config['error_invalid_email']

When an email address fails the email check, if there is no custom error message set for a field, this value will be used.

$config['error_invalid_email'] = 'Please enter a valid email address.';

$config['error_invalid_number']

When a field fails the number check, if there is no custom error message set for a field, this value will be used.

$config['error_invalid_number'] = 'Please enter a valid number.';

$config['error_invalid_length']

If a set length is defined for a field in $config['fields'] and the submitted value fails the length check, if there is no custom error message set for a field, this value will be used.

$config['error_invalid_length'] = 'A field is not of the correct length.';

$config['error_missing_field']

If a field is marked as required in $config['fields'] and no value is submitted, if there is no custom error message set for a field, this value will be used.

$config['error_missing_field'] = 'Please make sure all required fields are completed.';

Editing the Form

The layout of the form and its individual fields is found in the includes/form.php file. The layout is extremely flexible - you can completely change the code structure without breaking any of the script. However, there are a few required elements.

Fields

You can define form fields like you would in a standard HTML form. Ensure that the names match those used in the $config['fields'] array. You can set the value of a field to be filled if the form returns an error by setting the value attribute, as shown in the example below:

<input type="text" name="subject" value="<?php $this->value('subject'); ?>" />

In a textarea, the value is set between the tags:

<textarea name="content"><?php $this->value('content'); ?></textarea>

Security Hash

To prevent people constantly sending the same form multiple times, a hash is used to authenticate each session call. This is all done behind the scenes, but there is one form element which must be sent for it to work. Make sure that this code is somewhere inside your form:

<?php $this->generateHash(); ?>

Image Verification

The script has a built-in CAPTCHA function which can prevent automated bots from sending messages through your form, by asking users to enter five characters which are embedded in an image. When the CAPTCHA function is disabled, but the human security question is enabled, users will be asked to complete a simple maths question.

To make it as easy as possible to switch between the two settings, the same code is used throughout. There are two snippets of code needed in your form to make it work:

<!-- This will display either the CAPTCHA or the security question -->
<?php $this->getCaptcha(); ?>

and:

<!-- This is the corresponding form field where the user enters the answer -->
<input type="text" name="captcha" id="captcha" size="10" />

Submit Button

The form submit button must be named "submit" for the script to detect that a form is being sent.

<input type="submit" name="submit" class="button" value="Send Message" />

Displaying Errors

Any user errors caught by the script are stored in the class, so you can use a PHP function to call them in the place you'd like them to display. The following code will check if there are any errors, and if there are, it will display them in an unordered list.


						<?php if ($this->hasErrors()) : ?>

						   <div class="error">

						      <p>The following errors occurred:</p>

						      <ul>

						         <?php $this->displayErrors("<li>","</li>"); ?>

						      </ul>

						   </div>

						<?php endif; ?>

You can change which tags get wrapped around each error message by altering the parameters to the $this->displayErrors(); function, so if you wanted to just show one on each line, you would need to change it to this:

<?php $this->displayErrors("","<br />"); ?>

Success Message

If there is no success page configured, a success message can be displayed on the form. To show this in your form, you need to add the following code:


						<?php if ($this->success()) : ?>

						   <div class="success">

						      <p><?php $this->getSuccess(); ?></p>

						   </div>

						<?php endif; ?>

Managing Fields

Adding Fields

It's quick and easy to add a new field to your form. First, make sure that you've added the new input field to includes/form.php. For example, if we were making a field for a telephone number, we would add this to the file:

<label for="telephone">Telephone:</label>

			<span>

				      <input type="text" name="telephone" id="telephone" value="<?php $this->value('telephone'); ?>" size="40" />

			</span>

We would then add the field to the $config['fields'] array in includes/config.php (around line 70) so that the script will check for the form. You can also add validation rules here.

$config['fields']['telephone'] = array();

Finally, we need to add it to the body of the email. You can skip this step if you have raw output enabled. You'll find the body setting around line 28 of the configuration file:

$config['body'] = "[[name]], with the telephone number [[telephone]], has sent you a message titled [[subject]]...";

After you've done that, your field should be ready to use. Read on for information on how to validate your form fields as emails, numbers and more.

Field Validation

The Awesome Contact Form has several validation filters built-in. These are simple to enable. The included methods are:

email validation
number validation
length validation
required fields

You can enable these by editing the $config['fields'] variable. Examples of each type are shown below:

	// required field

							$config['fields']['name'] = array("required" => true);

							

							// valid email address and required field

							$config['fields']['email'] = array("type" => "email", "required" => true);

							

							// telephone number of 11 digits

							$config['fields']['telephone'] = array("type" => "number", "length" => 11);

If a field validation check returns false, the script will first check to see if there is a custom error message set for the field. If not, it will use a default error message set in the config array.

Example Fields

Below is example code for each type of field you may want to use in your form.php template. For all field types, the code needed in config.php for the field is the same. See adding fields for an introduction.

Text

To add a textbox with the name myfield, you would need to add the following code:

<input type="text" name="myfield" id="myfield" value="<?php $this->value('myfield'); ?>" size="40" />

Textarea

To add a textarea with the name myfield, you would need to add the following code:

<textarea name="myfield" id="myfield"><?php $this->value('myfield'); ?></textarea>

Select

To add a dropdown field called department which had several options (eg. 'development', 'themes', 'support'), you would need to add the following code:

<select name="department" id="department">
   
	<option value="0" <?php $this->value('department', '0', 'selected="selected"'); ?>>Select..</option>
   
	<option value="Development" <?php $this->value('department', 'development', 'selected="selected"'); ?>>Dev</option>
   
	<option value="Themes" <?php $this->value('department', 'themes', 'selected="selected"'); ?>>Themes</option>
   
	<option value="Support" <?php $this->value('department', 'support', 'selected="selected"'); ?>>Support</option>

</select>

Note the use of the extra parameters in the <?php $this->value(); ?> function:


					<?php $this->value( field name, [wanted value], [code to display] ); ?>

The code passed as the third parameter will only get displayed if the field contains the wanted value.

Checkbox

To add a checkbox with the name myfield, you would need to add the following code:

<input type="checkbox" name="myfield" id="myfield" value="Yes" <?php $this->value('checkbox', 'Yes', 'checked'); ?> />

Like the select fields, this field uses the extended <?php $this->value(); ?> function which is described above.

It is also possible to have a checkbox group, and the script will automatically put the selected values into a comma-separated list in the email. To do this, you will need to add the following code to your form template:

<input type="checkbox" name="myfield[]" value="Value 1" <?php $this->value('myfield', 'Value 1', 'checked', true); ?> />Value 1

						<input type="checkbox" name="myfield[]" value="Value 2" <?php $this->value('myfield', 'Value 2', 'checked', true); ?> />Value 2

						<input type="checkbox" name="myfield[]" value="Value 3" <?php $this->value('myfield', 'Value 3', 'checked', true); ?> />Value 3

Note here the use of square brackets after the field name, which denotes a checkbox group, and also the fourth parameter for the <?php $this->value(); ?> function, which must be set to true for checkbox groups.

Radio Buttons

To add two radio buttons - one with the value 'Yes' and one with the value 'No' - with the name myfield, you would need to add the following code:

<input type="radio" name="myfield" value="Yes" <?php $this->value('checkbox', 'Yes', 'checked'); ?> />

						<input type="radio" name="myfield" value="No" <?php $this->value('checkbox', 'No', 'checked'); ?> />

Like the select field, this field uses the extended <?php $this->value(); ?> function which is described above.

Custom Error Messages

The custom error message feature allows you to override the default error messages shown when a field fails validation. It's quick and easy to set up. You can add custom error messages at the bottom of the configuration file. The array key must start with error_field_ and then contain the exact field name specified in $config['fields'].

Here are some examples using the common field names name, email, subject and content.


					$config['error_field_name'] = "Please enter a name.";

					$config['error_field_email'] = "Please enter a valid email.";

					$config['error_field_subject'] = "Please enter a subject.";

					$config['error_field_content'] = "Please enter a message.";

Multiple Forms

It is possible to run multiple forms from the same installation of the script, each with their own template and configuration. It is advised that you have some beginner PHP knowledge if trying this.

The Contact_Form class takes two extra, but optional parameters when it is created - where you can specify an alternate configuration file and an alternate form template. By setting these, the script will ignore the default files and will use the files you specify.

You would set these at the top of your site page where you are embedding the form:


					<?php

					include('includes/contact.php');

					$myform = new Contact_Form( 'includes/my_config.php', 'includes/my_form.php' );

					?>

To avoid potential conflicts, don't name your object variable $form. In the example above, we used $myform and so all script calls would have to be made as <?php $myform->displayForm(); ?> instead of the default.

The last thing needed is to give your second form a unique ID. Open your new configuration file and set the $config['identifier'] string. This stops form sessions from conflicting with each other.

Image Verification

If you plan to use the CAPTCHA image verification feature, then you will also need to duplicate the includes/captcha.php file (eg. includes/my_captcha.php).

Change line 16 to include your configuration path. Remember that it needs to be relative to the new CAPTCHA file! (In the example we are assuming the new file is inside the same folder as our new configuration file)


					$contact_form = new Contact_Form('my_config.php','my_form.php');

Finally, you will need to update your new configuration file to point to the new CAPTCHA. Adjust the $config['captcha_path'] variable to point to the new file.

That's all you need to do. You can repeat these steps for as many forms as you need.

Handling Form Data

You can now easily pass form data from the contact form to another script on your site, through PHP session variables. To enable this, make sure that $config['save_session'] is set to TRUE, and make a note of the value set in $config['identifier'].

The saved form data is stored in $_SESSION['acf_identifier_data'], where identifier is the value of $config['identifier']. For example, you could var_dump all the form data saved with a simple script:


					<?php

					session_start();

					var_dump($_SESSION['acf_contact-form_data']);

					?>

To access a single variable, for example email, you could use this:


					<?php

					session_start();

					echo $_SESSION['acf_contact-form_data']['email'];

					?>

Note that both these examples would only work after the form had been saved, and it is suggested you check for the presence of the session variable before trying to output its contents to avoid any errors.

Help and Support

If you have any queries or need any help with the script, feel free to email me through my user page on CodeCanyon.

Credits

The script and all accompanying documentation was created by Jordan Hatch. Icons by famfamfam and 32px mania.

Awesome Contact Form

Contents

File Structure

Installation

Upgrading

Upgrading from v1.2

Upgrading from v1.1

Upgrading from v1.0

Configuration

$config['address']

$config['subject']

$config['body']

$config['raw']

$config['sender_copy']

$config['sender_email']

$config['sender_subject']

$config['sender_body']

$config['success_page']

$config['success_message']

$config['fields']

$config['email_field']

$config['use_captcha']

$config['captcha_path']

$config['captcha_base']

$config['use_check']

$config['identifier']

$config['save_session']

$config['show_errors']

$config['error_invalid_email']

$config['error_invalid_number']

$config['error_invalid_length']

$config['error_missing_field']

Editing the Form

Fields

Security Hash

Image Verification

Submit Button

Displaying Errors

Success Message

Managing Fields

Adding Fields

Field Validation

Example Fields

Text

Textarea

Select

Checkbox

Radio Buttons

Custom Error Messages

Multiple Forms

Image Verification

Handling Form Data

Help and Support

Credits