CHAPTER 11 ■ THE FORM API

// Store the allowed choices in the form definition. $allowed_flavors = array(t('spicy'), t('sweet')); $form['flavor'] = array(

'#type' => 'textfield', '#title' => 'flavor',

'#allowed_flavors' => $allowed_flavors, '#element_validate' => array('formexample_flavor_validate')

);

Then your element validation function would look like this:

function formexample_flavor_validate($element, $form_state) {

if (!in_array($form_state['values']['flavor'], $element['#allowed_flavors'])) { form_error($element, t('You must enter spicy or sweet.'));

}

}

The validation function for the form will still be called after all element validation functions have been called.

■ Tip Use form_set_error() when you have the name of the form element you wish to file an error against and form_error() when you have the element itself. The latter is simply a wrapper for the former.

Form Rebuilding

During validation, you may decide that you do not have enough information from the user. For example, you might run the form values through a textual analysis engine and determine that there is a high probability that this content is spam. As a result, you want to display the form again (complete with the values the user entered) but add a CAPTCHA to disprove your suspicion that this user is a robot. You can signal to Drupal that a rebuild is needed by setting $form_state['rebuild'] inside your validation function, like so:

$spam_score = spamservice($form_state['values']['my_textarea']; if ($spam_score > 70) {

$form_state['rebuild'] = TRUE; $form_state['formexample']['spam_score'] = $spam_score;

}

In your form definition function, you would have something like this:

262

CHAPTER 11 ■ THE FORM API

function formexample_nameform($form_state) { // Normal form definition happens.

...

if (isset($form_state['formexample']['spam_score']) {

//If this is set, we are rebuilding the form;

//add the captcha form element to the form.

...

}

...

}

Writing a Submit Function

The submit function is the function that takes care of actual form processing after the form has been validated. It executes only if form validation passed completely and the form has not been flagged for rebuilding. The submit function is expected to modify $form_state['redirect'].

function formexample_form_submit($form, &$form_state) {

//Do some stuff.

...

//Now send user to node number 3. $form_state['redirect'] = 'node/3';

}

If you have multiple functions handling form submittal (see the “Submitting the Form” section earlier in this chapter), the last function to set $form_state['redirect'] will have the last word.

■ Tip The $form_state['rebuild'] flag can be set in submit functions too, just like in validation functions. If set, all submit functions will run but any redirect value will be ignored, and the form will be rebuilt using the submitted values. This can be useful for adding optional fields to a form.

Changing Forms with hook_form_alter()

Using hook_form_alter(), you can change any form. All you need to know is the form’s ID. There are two approaches to altering forms.

Altering Any Form

Let’s change the login form that is shown on the user login block and the user login page.

263

CHAPTER 11 ■ THE FORM API

function formexample_form_alter(&$form, &$form_state, $form_id) {

//This code gets called for every form Drupal builds; use an if statement

//to respond only to the user login block and user login forms.

if ($form_id == 'user_login_block' || $form_id == 'user_login') { // Add a dire warning to the top of the login form. $form['warning'] = array(

'#markup' => t('We log all login attempts!'), '#weight' => -5

);

// Change 'Log in' to 'Sign in'. $form['submit']['#value'] = t('Sign in');

}

}

Since $form is passed by reference, we have complete access to the form definition here and can make any changes we want. In the example, we added some text using the default form element (see “Markup” later in this chapter) and then reached in and changed the value of the Submit button.

Altering a Specific Form

The previous approach works, but if lots of modules are altering forms and every form is passed to every hook_form_alter() implementation, alarm bells may be going off in your head. “This is wasteful,” you’re probably thinking. “Why not just construct a function from the form ID and call that?” You are on the right track. Drupal does exactly that. So the following function will change the user login form too:

function formexample_form_user_login_alter(&$form, &$form_state) { $form['warning'] = array(

'#value' => t('We log all login attempts!'), '#weight' => -5

);

// Change 'Log in' to 'Sign in'. $form['submit']['#value'] = t('Sign in');

}

The function name is constructed from this:

modulename + 'form' + form ID + 'alter'

For example,

'formexample' + 'form' + 'user_login' + 'alter'

results in the following:

formexample_form_user_login_alter

In this particular case, the first form of hook_form_alter() is preferred, because two form IDs are involved (user_login for the form at http://example.com/?q=user and user_login_block for the form that appears in the user block).

264

CHAPTER 11 ■ THE FORM API

Submitting Forms Programmatically with drupal_form_submit()

Any form that is displayed in a web browser can also be filled out programmatically. Let’s fill out our name and favorite color programmatically:

$form_id = 'formexample_nameform'; $form_state['values'] = array(

'user_name' => t('Marvin'), 'favorite_color' => t('green')

);

// Submit the form using these values. drupal_form_submit($form_id, $form_state);

That’s all there is to it! Simply supply the form ID and the values for the form, and call drupal_form_submit().

■ Caution Many submit functions assume that the user making the request is the user submitting the form. When submitting forms programmatically, you will need to be very aware of this, as the users are not necessarily the same.

Dynamic Forms

We’ve been looking at simple one-page forms. But you may need to have users fill out a form that dynamically displays elements on the form based on selections the user made as he or she filled out the form. The following example demonstrates how to display form elements dynamically as the user picks various options while filling out the form.

Start by creating a directory in your site/all/modules/custom folder named form_example_dynamic. In that directory, create a form_example_dynamic.info file with the following information.

name = Form Example – Creating a Dynamic Form description = An example of a dynamic form. package = Pro Drupal Development

core = 7.x files[]=form_example_dynamic.module

Next create the form_example_dynamic.module file, and begin by placing the following header information in the file.

265

CHAPTER 11 ■ THE FORM API

<?php

/**

*@file

*An example of how to use the new #states Form API element, allowing

*dynamic form behavior with very simple setup.

*/

With the header information in place, the next step is to create a menu item that a visitor can use to access the new form. The module provides a single menu entry that can be accessed via www.example.com/form_example_dynamic.

/**

* Implements hook_menu(). */

function form_example_dynamic_menu() { $items['form_example_dynamic'] = array(

'title' => t('Form Example Dynamic Form'), 'page callback' => 'drupal_get_form',

'page arguments' => array('form_example_dynamic_form'), 'access callback' => TRUE,

'type' => MENU_NORMAL_ITEM

);

return $items;

}

With the menu complete, I’m now ready to create the form. The first item displayed on the form is a series of three radio buttons that allow a site visitor to select a room type to reserve.

function form_example_dynamic_form($form, &$form_state) { $form['room_type'] = array(

'#type' => 'radios',

'#options' => drupal_map_assoc(array(t('Study Room'), t('Small Conference Room'), t('Board Room'))),

'#title' => t('What type of room do you require?')

);

The next form item is a fieldset that contains details about the study room and uses the #states attribute to determine whether this item should be displayed on the page. The #states attribute sets whether the fieldset will be visible by examining the room_type radio buttons to see whether the Study Room option was selected. If the Study Room option was selected, then the value is set to true and the form will render the fieldset using jQuery. The syntax of the visibility test follows the syntax of using selectors in jQuery. In this case, we’re looking at an input element (the radio buttons) named room_type. We’re examining whether the value of the input is Study Room.

266

CHAPTER 11 ■ THE FORM API

$form['study_room'] = array( '#type' => 'fieldset',

'#title' => t('Study Room Details'), '#states' => array(

'visible' => array(

':input[name="room_type"]' => array('value' => t('Study Room')),

),

),

);

The next item shown on the form is two check boxes that allow a visitor to provide details about the types of equipment to be set up in the study room. In the example, I’ve limited those choices to chairs and a PC. I use the same #states approach as the preceding fieldset. I want the check boxes displayed only if the visitor has selected Study Room from the list of available rooms.

$form['study_room']['equipment'] = array( '#type' => 'checkboxes',

'#options' => drupal_map_assoc(array(t('Chairs'), t('PC'))), '#title' => t('What equipment do you need?'),

'#states' => array(

'visible' => array( // action to take. ':input[name="room_type"]' => array('value' => t('Study Room')),

),

),

);

If the user checked the Chairs check box, I’ll display a text field that allows the visitor to enter the number of chairs to be set up in the room prior to his or her arrival. I’m using #action to control visibility of this text field, displaying the field only if the user checked the Chairs check box.

$form['study_room']['chairs'] = array( '#type' => 'textfield',

'#title' => t('How Many Chairs Do You Need?:'), '#size' => 4,

'#states' => array(

'visible' => array( // action to take. ':input[name="equipment[Chairs]"]' => array('checked' => TRUE),

),

),

);

The next element on the form is another text box that allows a visitor to enter details about the type of PC to be set up in the study room. Like the foregoing chairs item, I’m using #action to control visibility by checking to see whether the visitor checked the PC check box.

$form['study_room']['pc'] = array( '#type' => 'textfield',

'#title' => t('What Type of PC do you need?:'), '#size' => 15,

267

CHAPTER 11 ■ THE FORM API

'#states' => array(

'visible' => array( // action to take. ':input[name="equipment[PC]"]' => array('checked' => TRUE),

),

),

);

The next set of form elements is displayed only if the visitor clicked the “Small Conference Room” radio button. It follows the same pattern of using the #actions attribute to determine whether form items should be visible based on a condition or action taken by the visitor.

$form['small_conference_room'] = array( '#type' => 'fieldset',

'#title' => t('small_conference_room Information'), '#states' => array(

'visible' => array(

':input[name="room_type"]' => array('value' => t('Small Conference Room')),

),

),

);

$form['small_conference_room']['how_many_pcs'] = array( '#type' => 'select',

'#title' => t('How many PCs do you need set up in the small conference room?'), '#options' => array(

1 => t('One'),

2 => t('Two'),

3 => t('Three'),

4 => t('Four'),

5 => t('Lots'),

),

);

$form['small_conference_room']['comment'] = array( '#type' => 'item',

'#description' => t("Wow, that's a long time."), '#states' => array(

'visible' => array(

':input[name="how_many_pcs"]' => array('value' => '5'),

),

),

);

$form['small_conference_room']['room_name'] = array( '#type' => 'textfield',

'#title' => t('Which room do you want to use?:'),

);

268

CHAPTER 11 ■ THE FORM API

$form['small_conference_room']['hours'] = array( '#type' => 'select',

'#options' => drupal_map_assoc(array(t('Free'), t('Paid'))),

'#title' => t('Do you want to reserve the room when it is free (no fees) or paid (prime time)?'),

);

The following form element utilizes two conditional checks to determine whether the text field should be displayed. With #action you can simply list out any number of conditions that must be met before the form item will be displayed. In this case, I check to see whether the visitor selected either Free or Paid from the preceding hours field.

$form['small_conference_room']['hours_writein'] = array( '#type' => 'textfield',

'#size' =>50,

'#title' => t('Please enter the date and time you would like to reserve the room and the duration.'),

'#states' => array(

'visible' => array( // Action to take: Make visible. ':input[name="hours"]' => array('value' => t('Free')), ':input[name="hours"]' => array('value' => t('Paid')),

),

),

);

The reminder form item here introduces a new visibility check by verifying that the visitor seleted either Free or Paid and that he or she entered something in the hours_writein field.

$form['small_conference_room']['reminder'] = array( '#type' => 'item',

'#description' => t('Remember to enter the date, start time, and end time.'), '#states' => array(

'visible' => array(

'input[name="hours"]' => array('value' => t('Free')), 'input[name="hours"]' => array('value' => t('Paid')), 'input[name="hours_writein"]' => array('filled' => TRUE),

),

),

);

$form['board_room'] = array( '#type' => 'fieldset',

'#title' => t('Board Room Information'), '#states' => array(

'visible' => array(

':input[name="room_type"]' => array('value' => t('Board Room')),

),

),

);

269

270

CHAPTER 11 ■ THE FORM API

With the module complete, I’ll enable the module and visit the form at www.example.com/form_example_dynamic. The first page of the form should look like Figure 11-7.

Figure 11-7. The initial state of the form

Selecting Study Room from the list of options reveals the next part of the form (see figure 11-8), which asks the visitor about the type of equipment to be set up in the room before he or she arrives.

Figure 11-8. Study Room Details fieldset is displayed based on the previous option selected.

271

CHAPTER 11 ■ THE FORM API

Selecting the Small Conference Room option instead of Study Room displays the form elements related to the Small Conference Room (see figure 11-9).

Figure 11-9. The Small Conference room form elements are displayed after selecting Small Conference room from the room types.

If the visitor selects the Board Room from the list of room types, the details shown in figure 11-10 are displayed.

272