Introduction

This is meant as a first effort at developing some of the child pages for the Comprehensive Form Documentation index that was created by Steve Jones.

For an interactive, data-driven website such as one built with Drupal, collecting and processing user submitted data will be exceptionally important. Most of this data can be captured using a web based form, i.e. an HTML structure with textfields and widgets for selecting different options.

The Drupal Form API allows for almost unlimited possibilities for custom theming, validation, and execution of forms. The idea of the API is to eliminate writing HTML for any form building and to make the flow of present-validate-execute as clean as possible. The API also allows for ways to manipulate multi-step forms by passing data from each stage of the multi-step process to the next seamlessly.

Why a Form API? Getting a form on to a web page is easy, and getting the user's responses is easy too --- getting them securely is much, much harder. Drupal's Form API provides a standard, easy to use, easy to extend, and secure way of adding forms to your Drupal website.

Even better, ANY form (even those in Drupal's core) can be altered in almost any way imaginable -- elements can be removed, added, and rearranged. The following pages are meant to be a comprehensive guide to this functionality --- they are currently in the state of being a good working foundation with which to do the most basic form creation, theming, validation, and execution; please add more information as you discover it.

Basic Concepts

A form is represented in Drupal via a structured array. The array contains elements representing each of the form's elements, as well as internal information constructed by Drupal, like the default theme for the form, the submission handlers and so on. The arrays can be built in a recursive manner, so that form elements within form elements (typically grouped inside a fieldset element), are simply written as an inner array that is a data element inside an outer array.

A form is typically rendered by passing in this array to the function drupal_get_form. A form by default will not have a submit button; one has to be either explicitly added by adding a 'submit' element, or by using Drupal's built-in function, system_settings_form.

During rendering, Drupal calls alteration hooks on the form. This means that at the point of form creation, other modules can have their say in what the form will look like. Alteration hooks can be set to alter the entire form or for each element in the form.

Once a form is rendered, its submit action (that is, the action element for the form tag in the rendered HTML) is set to the same URL that generated the form in the first place. The reason this won't land you in an infinite loop is because when a form is generated from a form array, Drupal in fact first checks if the form already has some elements filled out and has been submitted (this is done via internal properties that Drupal sets on the form.)

If in fact a submitted form is encountered, Drupal's validation and submission routines kick in. The form will be validated and if there are errors, those will be displayed. If all validation routines pass, the submission handlers will be kicked off.

After submission handlers have been successfully executed, the default behavior is to return to the same page that generated the form. There are multiple ways of redirecting the user to another page after form submission.

The following sections explore this workflow in greater detail.