Drupal 6: Customizing individual checkboxes in hook_form_alter()

When hook_form_alter() is called, form elements of type ‘checkboxes’ are not yet expanded to individual checkbox elements:

Array
(
    [#title] => Options
    [#type] => checkboxes
    [#options] => Array
        (
            [opt_1] => Option 1
            [opt_2] => Option 2
            [opt_3] => Option 3
            [opt_4] => Option 4
        )
 
    [#default_value] => Array
        (
        )
)


If for example we wanted to add a description to each of the checkboxes we could call expand_checkboxes() passing as an argument the checkboxes element.

For the element shown above this call returns:

Array
(
    [#title] => Options
    [#type] => checkboxes
    [#options] => Array
        (
            [opt_1] => Option 1
            [opt_2] => Option 2
            [opt_3] => Option 3
            [opt_4] => Option 4
        )
 
    [#default_value] => Array
        (
        )
 
    [#tree] => 1
    [opt_1] => Array
        (
            [#type] => checkbox
            [#processed] => 1
            [#title] => Option 1
            [#return_value] => opt_1
            [#default_value] => 
            [#attributes] => 
            [#ahah] => 
        )
 
    [opt_2] => Array
        (
            [#type] => checkbox
            [#processed] => 1
            [#title] => Option 2
            [#return_value] => opt_2
            [#default_value] => 
            [#attributes] => 
            [#ahah] => 
        )
 
    [opt_3] => Array
        (
            [#type] => checkbox
            [#processed] => 1
            [#title] => Option 3
            [#return_value] => opt_3
            [#default_value] => 
            [#attributes] => 
            [#ahah] => 
        )
 
    [opt_4] => Array
        (
            [#type] => checkbox
            [#processed] => 1
            [#title] => Option 4
            [#return_value] => opt_4
            [#default_value] => 
            [#attributes] => 
            [#ahah] => 
        )
)

We can then replace the original checkboxes element in the form with its expanded version and have access to each of the checkboxes individually.

Here is a sample hook_form_alter() that adds descriptions to checkboxes:

function mymodule_form_alter(&$form, $form_state, $form_id) {
  switch ($form_id) {
    case 'mymodule_settings_form':
 
      // get a reference to the checkboxes form element
      $form_elem = &$form['settings']['options'];
 
      // replace the element with its expanded items
      $form_elem = expand_checkboxes($form_elem);
 
      // get the child elements
      $items = element_children($form_elem);
 
      // modify the child elements
      foreach($items as $item_key) {
 
        // get a reference to the child element
        $elem = &$form_elem[$item_key];
 
        // customize the child element
        $elem['#description'] = t('Description of @elem_title', array('@elem_title' => $elem['#title']));
      }
      break;
  }
}
This entry was posted in Drupal and tagged , , . Bookmark the permalink.

Leave a Reply

Your email address will not be published. Required fields are marked *