Customising cforms2 – A wordpress plugin

As you may be aware I’m a firm supporter of using Wordpress on small websites as it gives web developers a quick and easy path to giving small businesses a cost effective web presence. But what happens when a Wordpress plugin only gets you 80% of the way there?

So today this blog post is about customising the excellent cformsII wordpress plugin which allows developers and end users alike to create fully featured contact and data capture forms within a Wordpress based website.

I’ve got a requirement where I use the cformsII plugin to create a membership registration form. The extra requirements for this registration form are that alongside the normal input checking for the form – I also need to check that an email address has not already been used within the Wordpress database for a user.

Unfortunately, cforms2 does not natively support this so I need to customise the plugin. To keep this customisation to a minimum I’m going to change the least amount of the cforms core to acheive the ability to validate this email address against the database.

Here goes, code examples follow along with some caveats:

1. These code examples need basic understanding of PHP as to how and why things are done.
2. Your cforms form must not be AJAX enabled – otherwise the validation routines do not work.
3. You should always make a backup of your plugins directory before modifying any plugins

To start off with we need to change the cforms lib_validate.php which can be located in your ./wp-content/plugins/cforms/ directory of your wordpress installation. You need to go to approximately line 203 of this file, you’ll see following line of code around line 203:

$all_valid = $all_valid && $validations[$i+$off];

Directly above this line you’ll need to cut and paste the following code. This code instructs cforms to pass the form field data to your custom validation function. It also passes the results of the validations cforms has already performed on the field so that you can selectively choose to process the field again.

if(function_exists('cforms_custom_validation'))
{
    $result = cforms_custom_validation($input_name[1], $current_field, $field_type, $validations[$i+$off], $c_err[1]);
    $validations[$i+$off] = $result[0];
    if($result[0] == false)
    {
        $c_err[1] = $result[1];
        $err = 1;
    }
}

Next we need to make use of the code we’ve just inserted into the core of cforms2. To do this we need to create the following directory & file, or edit the file:

(wordpress installation root)/wp-content/plugins/cforms-custom/my-functions.php

and insert the following code:

function cforms_custom_validation($fieldId, $fieldValue, $fieldType, $existingResult, $existingError)
{
    // Create an array $returnValue which contains a default return value, this array is comprised
    // of the first element being the existing validation result so you can check if cforms has
    // already validated it as bad. The second element of the array is incase cforms has given
    // any custom error message which you may need to re-use.
    $returnValue = array($existingResult, $existingError);
    // Check two things before running the custom validation:
    // 1.) That cforms hasn't already marked this field as invalid, and;
    // 2.) Check the $fieldId passed is the one I want - this should be more robust, but suits my needs
    if($existingResult == true && $fieldId == 'Email address[id:user-email]')
    {
        //do custom validation
        $result = TonicUser::Exists($fieldValue);
        if($result->status == true)
        {
            //set the return value: the first element being false, as the validation failed. The second being 'Oops' which is your failure message.
            $returnValue = array(false, 'Your email address has already been used to register an organisation');
        }
    }
    return $returnValue;
}

You’ll see a comparison being made: $fieldId == ‘Email address[id:user-email]‘ . The ‘Email address[id:user-email]‘ part is directly related to the following screenshot. I hope the comments against the rest of the code are relatively self explanatory.

Screenshot showing the field id used in the code comparison

Hope that helps WP users.