Create a Simple Drupal Module - Use the Form API -- An Introduction

In this diary, we'll construct a simple custom drupal module.

Feel free to post questions in the comment area. Beginners are welcome. In this diary,  we won't assume "you are just supposed to know that". 

The goals of this post is to detail:

  • How to construct a data entry (web) form.
    • What is the Drupal Form API and how do I use it.
    • How to  test your form is working.
    • How to connect your form to the database.
  • How to create a report page.
  • How to add a navigation menu so website vistors can find and use my custom module?
  • Basic database use
    • How to create a custom database table
    • How do I add records to the custom database table
    • How do I retrieve and display values store in a custom database table.
  • Files and Directory Names and Locations
    • What should the name of my module file be? (How to name your module).
    • Where do I save my module files.
    • Should I create a new directory for my module?

We'll answer all of the above questions in a series of blog posts. This post is an introduction.

Let's get started  -- Let's Design

Before we starting writing computer instructions. Let's design our module first. Let's talk about why we need the module,  what the module will do, what the module won't do.

Why: Provides a simple example for beginning Drupal developers. Demonstrates basic module construction.

What Does it Do: Our module will be called "My Color". Allows folks to enter a color (e.g. red, white or blue) in a data entry form. Reports and displays a list of colors folks have entered through our data entry form.

What Our Does Not Do: Let's keep it simple. We won't provide a "delete" color function. We won't provide a "modify" color function.

Since "My Color" is a teaching tool, we won't provide an "un-install" function. Nor will we include any adminstrative settings.

Pre-requisites: You need to have Drupal installed already. We will be working with the 6.X version.

We prefer that you are working with an installation of Drupal on your local (home) computer. Working with web hosting services can add complications that will divert our attention.

If you've just been hired to change an existing Drupal website, we do not recommend performing the "My Color" exercise described in this diary on a production website. Always best to test your changes on a local installation first.


  • You should have a programmers text editor. Don't use word processors like Microsoft Word.  We use either a simple editor like Jedit or an integrated development environment like netbeans (php version).
  • Currently Drupal supports 2 different database engines (MySql and Postgres). Although our favorite database engine is Postgres, we will use MySql during this diary. Most Drupal installations use MySql, therefore to "keep it simple", we will also use MySql.
  • Sorry, we don't use Microsoft products. We use linux exclusively. Our preferred linux distribution is Arch Linux. All that means is, this diary will not spend time on how to configure Microsoft products. You will need to ask those questions elsewhere.

Let's stop here. The next installment in this diary will cover files and directories.