CHAPTER 11 ■ THE FORM API

#states

Adds JavaScript to the element to allow it to have different active states.

#suffix

The string defined in this property will be added to the output when the element is rendered, just after the rendered element.

#theme

This optional property defines a string that will be used when Drupal looks for a theme function for this element. For example, setting #theme = 'foo' will cause Drupal to check the theme registry for an entry that corresponds with foo. See the “Finding a Theme Function for the Form” section earlier in this chapter.

#theme_wrappers

Theme function to call for the element, after the element and children are rendered, but before the #post_render functions are called.

#title

This string is the title of the element.

#tree

Used to allow collections of form elements. Normally applied to the "parent" element, as the #tree property cascades to sub-elements.

#weight

This property can be an integer or a decimal number. When form elements are rendered, they are sorted by their weight. Those with smaller weights “float up” and appear higher; those with larger weights “sink down” and appear lower on the rendered page.

Form Elements

In this section, we’ll present examples of the built-in Drupal form elements.

277

CHAPTER 11 ■ THE FORM API

Text Field

An example of a text field element follows:

$form['pet_name'] = array( '#title' => t('Name'), '#type' => 'textfield',

'#description' => t('Enter the name of your pet.'), '#default_value' => $user->pet_name,

'#maxlength' => 32, '#required' => TRUE, '#size' => 15, '#weight' => 5,

'#autocomplete_path' => 'pet/common_pet_names', );

$form['pet_weight'] = array( '#title' => t('Weight'), '#type' => 'textfield',

'#description' => t('Enter the weight of your pet in kilograms.'), '#field_suffix' => t('kilograms'),

'#default_value' => $user->pet_weight, '#size' => 4,

'#weight' => 10, );

This results in the form element shown in Figure 11-11.

Figure 11-11. The text field element

278

CHAPTER 11 ■ THE FORM API

The #field_prefix and #field_suffix properties are specific to text fields and place a string immediately before or after the text field input.

The #autocomplete property defines a path where Drupal’s automatically included JavaScript will send HTTP requests using jQuery. In the preceding example, it will query http://example.com/?q=pet/common_pet_names. See the user_autocomplete() function in modules/user/user.pages.inc for a working example.

Properties commonly used with the text field element follow: #attributes, #autocomplete_path (the default is FALSE), #default_value, #description, #field_prefix, #field_suffix, #maxlength (the default is 128), #prefix, #required, #size (the default is 60), #suffix, #title, #process (the default is array('ajax_process_form')), and #weight.

Password

This element creates an HTML password field, where input entered by the user is not shown (usually bullet characters are echoed to the screen instead). An example from user_login_block() follows:

$form['pass'] = array('#type' => 'password', '#title' => t('Password'),

'#maxlength' => 60, '#size' => 15, '#required' => TRUE,

);

Properties commonly used with the password element are #attributes, #description, #maxlength,

#prefix, #required, #size (the default is 60), #suffix, #title, #process (the default is array('ajax_ process_form')), and #weight. The #default_value property is not used with the password element for security reasons.

Password with Confirmation

This element creates two HTML password fields and attaches a validator that checks if the two passwords match. For example, this element is used by the user module when a user changes his or her password.

$form['account']['pass'] = array( '#type' => 'password_confirm',

'#description' => t('To change the current user password, enter the new password in both fields.'),

'#size' => 25,

);

Textarea

An example of the textarea element follows:

$form['pet_habits'] = array( '#title' => t('Habits'), '#type' => 'textarea',

279

280