Form validation is an essential part of any web system. You need to ensure that the user has added valid data and if not, show them a meaningful error message. Validation functions are normally implemented in the module where the form is defined. However, thanks to Drupal’s hook system, you can add a validation function to any Drupal form, even if you did not create the form. In this tutorial, you will learn how to add a validation function to the node article form. This is the form where you add content to the article content type and can be found here: node/add/article

Imagine you want to ensure users cannot add the following title: “the quick fox jumped over the lazy dog”. If they do, they should receive an error message and the title field should be highlighted to ensure they know which field has an invalid value.

For this tutorial, you will need to download and enable a module called devel so that you can use its Drupal Print Message (dpm) function.

Alter the form

To add the new validation function, you need to alter the form. You can do this by implementing hook_form_alter(). We covered this in Day 7 of Starting Drupal Module Development. You will need a custom module to implement hook_form_alter. In the example below, I am using the module created in Day 3 of Starting Drupal Module Development. If you have not signed up for it, you can do so here.

In our implementation of hook_form_alter, we will have a look at the validation functions already set for the article node form.

function starting_drupal_dev_form_alter(&$form, &$form_state, $form_id) {
  if ($form_id == 'article_node_form') {
    dpm($form['#validate']);
  }
} 

In the above code, we are first checking that the form id is article_node_form. And then, we are calling dpm($form[‘#validate’]), which will show us an array of the validation functions. $form[‘#validate’] is a form element which lists all of the validation functions for a given form.

When you hit node/add/article, you will see node_form_validate(), which is the core validator for node forms.


Add a validation handler to the form

You need to add your validation function to that array by adding the following: $form[‘#validate’][] = ‘starting_drupal_dev_form_validate’. $form[‘validate’] is an array and you can add to that with $form[‘#validate’][].

function starting_drupal_dev_form_alter(&$form, &$form_state, $form_id) {
  if ($form_id == 'article_node_form') {
    $form['#validate'][] = 'starting_drupal_dev_form_validate';
    dpm($form['#validate']);
  }
} 

You will see there are now two validation handlers, the core node_form_validate and the one that you added, starting_drupal_dev_form_validate.

Create the validation function

Now you need to add a function called starting_drupal_dev_form_validate().

function starting_drupal_dev_form_validate($form, &$form_state) {

} 

When the form is submitted, the form values will be held in $form_state. To see what is included in form_state(), add dpm($form_state); to the validation function.

function starting_drupal_dev_form_validate($form, &$form_state) {
  dpm($form_state);
}

You will then see an array with data from the form you just submitted. We are interested in the values that the user adds to the form, which is held in $form_state[‘values’].

In the validation function, you need to check the value of the title field, which is held in $form_state[‘values’][’title’]. If the value is “the quick fox jumped over the lazy dog” then set an error.

function starting_drupal_dev_form_validate($form, &$form_state) {
  if ($form_state['values']['title'] == 'the quick fox jumped over the lazy dog') {
    form_set_error('title', t('You have added an invalid title.'));
  }
}

Let’s break down the above function.

if ($form_state['values']['title'] == 'black') { … }

This is a simple PHP if statement. If the value of the title field is ‘the quick fox jumped over the lazy dog’, it will be true and the code inside the if statement will be executed.

form_set_error('title', t('You are not allowed to use "the quick fox jumped over the lazy dog" as a title.'));

The Drupal function form_set_error() is called. The first parameter is the name of the field that has caused the error. In our case, this is the title field. The field specified will be highlighted with a red border, so the user has a clear visual cue as to which field has not validated. The second parameter is the error message, which will be displayed in the message area of the page.

Make multiple titles invalid

Now let’s take this one step further. Let’s make two phrases invalid, rather than just one. The second invalid title is “birds of a feather flock together”.

To do that, the validation function will become:

function starting_drupal_dev_form_validate($form, &$form_state) {
  $invalid_titles = array('the quick fox jumped over the lazy dog', 'birds of a feather flock together');
  if (in_array($form_state['values']['title'], $invalid_titles)) {
    form_set_error('title', t('You have added an invalid title.'));
  }
}

Let’s break this down.

$invalid_titles = array('the quick fox jumped over the lazy dog', 'birds of a feather flock together'); 

First, we have created an array of invalid titles.

 if (in_array($form_state['values']['title'], $invalid_titles)) { .. }

Then we check if the title that the user has added is in that array using PHP’s in_array function. If it is, the if statement will return true and the form_set_error will be set. You can add as many invalid titles as you like to the $invalid_titles array.

And that is all there is to it. There is much more you can do with validation handlers, which we will get into in later tutorials.