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.

Contents

  1. File Structure
  2. Installation
  3. Configuration
    1. $config['address']
    2. $config['subject']
    3. $config['body']
    4. $config['raw']
    5. $config['sender_copy']
    6. $config['sender_email']
    7. $config['sender_subject']
    8. $config['sender_body']
    9. $config['success_page']
    10. $config['success_message']
    11. $config['fields']
    12. $config['use_captcha']
    13. $config['captcha_path']
    14. $config['captcha_base']
    15. $config['use_check']
    16. $config['error_invalid_email']
    17. $config['error_invalid_number']
    18. $config['error_invalid_length']
    19. $config['error_missing_field']
  4. Editing the Form
    1. Fields
    2. Security Hash
    3. Image Verification
    4. Submit Button
    5. Displaying Errors
    6. Success Message
  5. Managing Fields
    1. Adding Fields
    2. Field Validation
  6. Custom Error Messages
  7. Help and Support
  8. Credits

File Structure

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

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. 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! Well, the hard part done anyway. The form should now show on your site, but you'll need to configure it a little first. You can find all the options in the includes/config.php file. The available options are documented below.

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

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@jordanh.net';

$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['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['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:

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.

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.";

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.