CHAPTER 11 ■ THE FORM API

$options = array( array(

t('Healthy') => array( 1 => t('wagging'), 2 => t('upright'), 3 => t('no tail')

),

),

array(

t('Unhealthy') => array( 4 => t('bleeding'),

5 => t('oozing'),

),

),

);

$form['pet_tail'] = array( '#title' => t('Tail demeanor'), '#type' => 'select',

'#description' => t('Pick the closest match that describes the tail of your pet.'),

'#options' => $options, '#multiple' => FALSE, '#weight' => 20,

);

Figure 11-12. A select element using choice grouping

Selection of multiple choices is enabled by setting the #multiple property to TRUE. This also changes the value in $form_state['values'] from a string (e.g., 'pet_tail' = '2', assuming upright is selected in the preceding example) to an array of values (e.g., pet_tail = array( 1 => '1', 2 => '2') assuming wagging and upright are both chosen in the preceding example).

Properties commonly used with the select element are #attributes, #default_value, #description,

#multiple, #options, #prefix, #required, #suffix, #title, #process (the default is array('form_ process_select', 'ajax_process_form')), and #weight.

Radio Buttons

A radio button example from modules/block/block.admin.inc follows:

281

CHAPTER 11 ■ THE FORM API

$form['user_vis_settings']['custom'] = array( '#type' => 'radios',

'#title' => t('Custom visibility settings'), '#options' => array(

t('Users cannot control whether or not they see this block.'), t('Show this block by default, but let individual users hide it.'), t('Hide this block by default but let individual users show it.')

),

'#description' => t('Allow individual users to customize the visibility of this block in their account settings.'),

'#default_value' => $edit['custom'],

);

Properties commonly used with this element are #attributes, #default_value, #description,

#options, #prefix, #required, #suffix, #title, and #weight. Note that the #process property is set to array('form_process_radios') (see includes/form.inc) by default.

Check Boxes

An example of the check boxes element follows. The rendered version of this element is shown in Figure 11-13.

$options = array(

'poison' => t('Sprays deadly poison'), 'metal' => t('Can bite/claw through metal'), 'deadly' => t('Killed previous owner') );

$form['danger'] = array(

'#title' => t('Special conditions'), '#type' => 'checkboxes',

'#description' => (t('Please note if any of these conditions apply to your pet.')),

'#options' => $options, '#weight' => 25,

);

Figure 11-13. An example using the check boxes element

282

CHAPTER 11 ■ THE FORM API

The array_filter() function is often used in validation and submission functions to get the keys of the checked boxes. For example, if the first two check boxes are checked in Figure 11-13, $form_state['values']['danger'] would contain the following:

array(

'poison' => 'poison', 'metal' => 'metal', deadly' => 0,

)

Running array_filter($form_state['values']['danger']) results in an array containing only the keys of the checked boxes: array('poison', 'metal').

Properties commonly used with the check boxes element are #attributes, #default_value,

#description, #options, #prefix, #required, #suffix, #title, #tree (the default is TRUE), and #weight. Note that the #process property is set to form_process_checkboxes() (see includes/form.inc) by default.

Value

The value element is used to pass values internally from $form to $form_state['values'] without ever being sent to the browser, for example:

$form['pid'] = array( '#type' => 'value', '#value' => 123,

);

When the form is submitted, $form_state['values']['pid'] will be 123.

Do not confuse #type => 'value' and #value => 123. The first declares what kind of element is being described, and the second declares the value of the element. Only #type and #value properties may be used with the value element.

Hidden

This element is used to pass a hidden value into a form using an HTML input field of type hidden, as in the following example.

$form['my_hidden_field'] = array( '#type' => 'hidden',

'#value' => t('I am a hidden field value'),

);

If you want to send a hidden value along through the form, it’s usually a better idea to use the value element for this, and use the hidden element only when the value element does not suffice. That’s because the user can view the hidden element in the HTML source of a web form, but the value element is internal to Drupal and not included in the HTML.

Only the #prefix, #suffix, #process (the default is array('ajax_process_form')), and #value properties are used with the hidden element.

283

CHAPTER 11 ■ THE FORM API

Date

The date element, as shown in Figure 11-14, is a combination element with three select boxes:

$form['deadline'] = array( '#title' => t('Deadline'), '#type' => 'date',

'#description' => t('Set the deadline.'), '#default_value' => array(

'month' => format_date(time(), 'custom', 'n'), 'day' => format_date(time(), 'custom', 'j'), 'year' => format_date(time(), 'custom', 'Y'),

),

);

Figure 11-14. A date element

Properties commonly used by the date element are #attributes, #default_value, #description,

#prefix, #required, #suffix, #title, and #weight. The #process property defaults to call array('form_process_date'), in which the year selector is hard-coded to the years 1900 through 2050. The #element_validate property defaults to date_validate() (both functions can be found in includes/form.inc). You can define these properties when defining the date element in your form to use your own code instead.

Weight

The weight element (not to be confused with the #weight property) is a drop-down used to specify weights:

$form['weight'] = array( '#type' => 'weight', '#title' => t('Weight'), '#default_value' => 0, '#delta' => 10,

'#description' => t('In listings, the heavier vocabularies will sink and the lighter vocabularies will be positioned nearer the top.'),

);

The preceding code will be rendered as shown in Figure 11-15.

284