Creating Basic Forms

If you come from a background where you have created your own forms directly in HTML, you may find Drupal's approach a bit baffling at first. The examples in this section are intended to get you started quickly with your own forms. To begin, we'll write a simple module that asks you for your name and prints it on the screen. We'll put it in our own module, so we don't have to modify any existing code. Our form will have only two elements: the text input and a submit button. We'll start by creating a .info file at sites/all/modules/custom/formexample/formexample.info and entering the following:

name = Form example description = Shows how to build a Drupal form. version = "$Name$"

Next, we'll put the actual module into sites/all/modules/custom/formexample/ formexample.module:

* Implementation of hook_menu().

function formexample_menu($may_cache) { $items = array(); if ($may_cache) { $items[] = array( 'path' => 'formexample', 'title' => t('View the form'), 'callback' => 'formexample_page', 'access' => TRUE

return $items;

* Called when user goes to example.com/?q=formexample

function formexample_page() { $output = t('This page contains our example form.');

// Return the HTML generated from the $form data structure. $output .= drupal_get_form('formexample_nameform'); return $output;

function formexample_nameform() { $form['user_name'] = array( '#title' => t('Your Name'), '#type' => 'textfield',

$form['submit'] = array( '#type' => 'submit', '#value' => t('Submit')

return $form;

function formexample_nameform_validate($form_id, $form_values) { if ($form_values['user_name'] == 'King Kong') { // We notify the form API that this field has failed validation. form_set_error('user_name', t('King Kong is not allowed to use this form.'));

* Handle post-validation form submission.

function formexample_nameform_submit($form_id, $form_values) { $name = $form_values['user_name'];

drupal_set_message(t('Thanks for filling out the form, %name', array('%name' => $name)));

We've implemented the basic functions you need to handle forms: one function to define the form, one to validate it, and one to handle form submission. Additionally, we implemented a menu hook and a function so that a URL could be associated with our function. If you're playing along at home and have installed this module, you can view the form at http://example. com/ ?q=formexample. Our simple form should look like the one shown in Figure 10-2.

Figure 10-2. A basic form for text input with a submit button

The bulk of the work goes into populating the form's data structure, that is, describing the form to Drupal. This information is contained in a nested array that describes the elements and properties of the form and is typically contained in a variable called $form.

The important task of defining a form happens in formexample_nameform() in the preceding example, where we're providing the minimum amount of information needed for Drupal to display the form.

â– Note What is the difference between a property and an element? The basic difference is that properties cannot have properties, while elements can. An example of an element is the submit button. An example of a property is the #type property of the submit button element. You can always recognize properties, because they are prefixed with the # character. We sometimes call properties keys, because they have a value, and to get to the value, you have to know the name of the key. A common beginner's mistake is to forget the # before a property name. Drupal, and you, will be very confused if you do this.

Was this article helpful?

0 0

Post a comment