You are here

How to Create a Custom Form in Drupal 7


After searching for a good tutorial on how to create a custom form in Drupal 7, and not finding anything that really showed the step-by-step process, I decided to create a tutorial. This tutorial will start off creating a very basic form, then increase the complexity of the form until, when we are done, we will have a form that uses AJAX to add dynamic elements and send an email showing the form data when it is submitted.

The tutorial is based on a form that I created for one of my clients.  The client was a private school that wanted to allow parents to request an enrollment interview through their website.  For reference, the final form can be see at  As you can see if you look at the form, it is fairly simple.  It gets the parent's contact information and the names and ages of all of the students who are being interviewed.  Some of the complexity in the form is the ability to add additional parent contact information and students using AJAX.

We will develop this form in a number of steps - each step adding to the previous step.  The steps are:

  1. Create a Drupal module for the form and implement the first version of the form.
  2. Update the form to allow additional parent contact information and students to be added using AJAX.
  3. Style the form using CSS.
  4. Validate the form content.
  5. Create an email message to the school's enrollment clerk indicating that there is a new enrollment request.
  6. Redirect the user on a successful submission.

It is important to keep in mind that this tutorial is for Drupal Version 7.  This will not work for earlier versions of Drupal.

Step 1 - Create Drupal 7 Module and Basic Form

In order to show how to create a custom form, we are going to create a Drupal 7 module.  This tutorial isn't about creating a module, so we will just show the basic files necessary to create on.  Let's call our module form_tutorial.  The name of the module will determine the names of the files and functions that you will need to create for your form.  You will need to create the following two files:

  • - This file describes the module to Drupal.
  • form_tutorial.module - This file contains the php code that implements the module.

These files would be created in a new directory called form_tutorial in the sites/all/modules directory of your Drupal installation.  The following code segments show the contents of the two files.

name = Form Tutorial
description = Drupal 7 Step-by-Step Form Tutorial
package = Tutorials
core = 7.x
version = 7.x-0.2
file[] = form_tutorial.module

The contents of the file are pretty self explanatory.  The file[] list indicates all of the files that are part of the module.

 * Implements hook_menu()
function form_tutorial_menu()
  $items = array();

  // Register the step 1 tutorial URL.
  $items['tutorials/form/step1'] = array('title' => 'Form Tutorial Step 1',
                                         'page callback' => 'drupal_get_form',
                                         'page arguments' => array('form_tutorial_step_1'),
                                         'access callback' => TRUE,
                                         );  return $items;

 * Render the form.
function form_tutorial_step_1($form, &$form_state)
  // Set the page description.
  $form['description'] = array('#markup' => '<div>'
                               . t('This demonstrates the very basic Drupal 7 form APIs')
                               . '</div>',

  // Create the parent textfield.
  $form['parent'] = array('#type' => 'textfield',
                          '#title' => t('Parent Name'));

  // Create the parent textfield.
  $form['student'] = array('#type' => 'textfield',
                           '#title' => t('Student Name'));

  // Create the submit button.
  $form['submit'] = array('#type' => 'submit',
                          '#value' => t('Submit'));

  return $form;

 * Handle the submit.
function form_tutorial_step_1_submit($form, &$form_state)
  $output = t('You submitted Parent: @p and Student: @s',
              array('@p' => $form_state['values']['parent'],
                    '@s' => $form_state['values']['student']));

form_tutorial.module contains the PHP code that implements the form.  The function form_tutorial_menu() overrides the hook_menu() and creates the URL link to the form PHP function - in this case form_tutorial_form().  For more information on hook_menu see:!system!system.api.php/function/hook_menu/7.  The form_tutorial_from() function takes two arguments, the form and the form_state.  The form argument is typically modified in the form function to add the form elements.  In the example, a description, two form text elements and a submit button are added to the form.  The modified form element is then returned.  The form_tutorial_submit() function handles the submit action.  The values set in the form are available in the form_state argument.  In this first, simple version of the form, we just output the values entered in the form.

Once you have created these files, you will be able to use Drupal's module configuration to enable the module.  Once the module is enabled, you will be able to go to the /tutorials/form/step1 URL and see your form.