A simple Drupal form example ("My first Drupal form")

Drupal form FAQ: Can you share an example of a simple Drupal form? (i.e., a "My first Drupal form" example.)

I've written before about the Drupal learning cliff (learning curve), and as that name implies, getting started with Drupal form development can be a little hard. To that end I'm taking this weekend to write all the form examples I can fit into one weekend.

A simple Drupal form example

To get the ball rolling, I've created a first Drupal form example, which will demonstrate one of the most simple forms you can create, with just one form textfield and a submit button.

This simple form example is a combination of several Drupal Form API examples on the Drupal website that start at this page. I originally started with a different approach, but I'm hoping that by following their Form API example syntax that you'll be able to back and forth between this form tutorial and their form examples.

NOTE: This Drupal module/form example was written for Drupal 6. I haven't tested it with Drupal 7 yet, but when I do I'll either update this tutorial or provide a modified version of this tutorial for Drupal 7.

Creating your first Drupal form

Here then is the step-by-step process to creating your first Drupal form.

1) Create your module directory

For Step 1, create this directory in your Drupal website:

sites/all/modules/firstmodule

For instance, if your Drupal website is located in a directory named /Users/al/drupal6, the full path to this directory would be:

/Users/al/drupal6/sites/all/modules/firstmodule

2) Create your Drupal module ".info" file

In that directory create a file named firstmodule.info, and put these contents in that file:

name = My first Drupal form
description = My first Drupal 6 form
core = 6.x

3) Create your Drupal form module file

Create a file named firstmodule.module in that same directory, then copy and paste these contents in that file:

<?php

# this function is the menu handler for our drupal form/module.
# it is an implementation of the Drupal hook_menu function.
function firstmodule_menu() {
  $items = array();
  $items['firstmodule/form'] = array(
    'title' => t('My first Drupal form'),
    'page callback' => 'firstmodule_form',
    'access arguments' => array('access content'),
    'description' => t('My first Drupal form'),
    'type' => MENU_CALLBACK,
  );
  return $items;
}

# the "callback" function; when the menu item or url is
# accessed, this function will be called
function firstmodule_form() {
  return drupal_get_form('firstmodule_form1');
}

# our drupal form "form builder" function
function firstmodule_form1($form_state) {

  # an html textfield for our drupal form
  $form['name'] = array(
    '#type' => 'textfield',
    '#title' => t('First Name'),
  );

  # an html submit button for our drupal form
  $form['submit'] = array(
    '#type' => 'submit',
    '#value' => 'Submit',
  );
  return $form;
}

# our drupal form submit handler (using a submit handler
# given by the default naming convention, i.e.,
# 'firstmodule_form1' plus '_submit')
function firstmodule_form1_submit($form, &$form_state) {
  drupal_set_message(t('The form has been submitted.'));
}

Note that it is correct to omit the closing PHP "?>" PHP tag.

4) Enable your Drupal form module

Next, go to the admin/build/modules page, and enable your "My first Drupal form" module. It should look like this on your Drupal modules administration page:

5) Visit your Drupal form web page

Now go to a URL like this one:

http://localhost/firstmodule/form

to see what your first Drupal form looks like. (Replace "localhost" with the name of your web server.) Here's what this Drupal form looks like on my test website using the default Drupal Garland theme:

Where did this URL come from? It came from the third line of our function definition above:

function firstmodule_menu() {
  $items = array();
  $items['firstmodule/form'] = array(

That "firstmodule/form" is the URI which people will use to access our first Drupal form.

My first Drupal form example - Discussion

I've documented the Drupal form code shown above quite a bit, so I won't add too much here at this time. The biggest thing to say is that you need to follow the Drupal Form API and module naming convention in several places. In most places above where you see the string "firstmodule", that string is either used because (a) it is required by the Drupal module and form naming convention, or (b) it is used to make the code more readable and consistent.

I can provide more details here if you're interested, but until any questions start rolling in, I'll just leave it at that.

My first Drupal module/form example - Summary

I hope this example/tutorial of how to create a simple Drupal form has been helpful. It does take a little time to get used to the Drupal form programming model, but once you learn the Drupal module and form programming fundamentals it turns out to be a very powerful programming framework.