As a Drupal developer, you’ll often find that a contributed module will make the first 90% of your development work on a Drupal website a breeze. Sometimes however, depending on the specific requirements of your project that last 10% can be an enormous pain, especially if your client wants a particular piece of functionality that the module you've chosen to use doesn't support out of the box.
The default field validation offered by the Webform module (https://www.drupal.org/project/webform) is one of those instances where nine times out of ten it will do exactly what you want. The rest of the time knowing how to write a custom validation handler to add any custom validation you require is a solid solution.
In the following tutorial we will be creating a webform that contains a single textfield. Next we’ll add a custom validation handler to ensure that the data entered in the field is follows the format LLNNNNNN (where L is letter and N is number) and that the data entered into the field does not exceed 8 characters in length.
Note: To follow along with this Tutorial you’ll need to set up an installation of Drupal 7 - preferably the latest version, which at the time of writing this is Drupal 7.36.
Creating your module files
In the modules directory of your Drupal 7 installation, create a new folder called “custom_webform_validation”. Inside the module folder create two new files with the names “custom_webform_validation.info” and “custom_webform_validation.module”.
Creating your form
Download the Webform module from drupal.org and extract the contents of the *.zip file to your modules directory. Once downloaded, log-in as an administrator (if you’re not already logged in) and navigate to the modules configuration page for your site (located at “admin/modules”). On the modules configuration page, scroll to the Webform group, check the “Enabled” checkbox and click “Save configuration” to enable the module.
Once the Webform module is installed if you navigate to “Add content” you’ll find that a new content type has been created titled “Webform”. We want to create a new Webform page, so navigate to “node/add/webform”, or simply click “Webform” on the “Add content” page.
On the Webform creation page the only required field is “Title” so lets type “Demo webform” into the title field and click “Save”.
On submission, you should be redirected to the “Form components” page where you will also see a message notifying you that the note has successfully been created.
The final step in the creation of our webform is to create a new component. As briefly touched upon at the start of this tutorial we’re going to create a “Textfield”, which should be selected by default under “Type”. Give the textfield a label of “Account ID”, ensure “Mandatory” is checked and click “Add”.
On the page “Edit component: Account ID” simply leave the values as-is, scroll to the bottom of the page and click “Save component”
Now if you click the “View” tab after being redirected back to the “Form components” page you should be presented with the following:
By clicking “Mandatory” we basically told the Webform module that the field had to contain something, which is fine, but Webform won’t actually check what that something is, so a user could feasibly enter whatever they want.
Defining your custom submit handler
Open the file “custom_webform_validation.info” that we created earlier and add the following code:
Here we’re defining the name and description of our module (both of which will appear on the module listing page), the version of Drupal required to use the module (so any version of Drupal in the 7.x range), the package (so what suite of modules it belongs to - if any) and any dependencies the module has (in this instance Webform is a dependency of the module).
We could technically switch the module on at this stage from the modules listing page, but it wouldn’t actually do anything, so let’s add some functionality to our *.module file.
Add the following code to the file “custom_webform_validation.module”:
Next, navigate to the modules page and switch on your newly created module.
If you navigate back to the form we created previously, you’ll notice that a green notification message has begun to appear at the top of the page (if it hasn’t try clearing the cache). Each of the items in the bulleted list shown is a form that is currently being rendered on the page you’re on.
Note down the name of the webform (in my case it’s “webform_client_form_5”) and go back to your *.module file and modify your “custom_webform_validation_form_alter()” hook so that it matches the following (where “webform_client_form_5” is the name of your form ID):
Here, if the form ID matches the ID of our webform we’re altering the $form array by adding a reference to our custom validation handler (which at this point doesn’t exist). Let’s add the validation handler next by adding the following code into our module:
All we have here is a very simple regular expression, which is checking our “account_id” field to see if it matches the format LLNNNNNN (where L is a letter - either uppercase, or lowercase - and N is a number).
If no match is found we’re then triggering the function “form_set_error()” (https://api.drupal.org/api/drupal/includes%21form.inc/function/form_set_error/7) which will return the user back to the form with the field where the error was detected highlighted and a descriptive message will appear at the top of the page to assist the user in correcting the error.
At this point you should be able to test your form to ensure that provided the format of the data in the field is entered correctly it passes - otherwise it fails.
All code produced in this tutorial can be downloaded from the following GIT repository https://github.com/craigweb/custom-webform-validation and as always if you have any questions please feel free to get in touch on Twitter @craigperks