function form_get_options in Drupal 5

Same name and namespace in other branches

1. 8 core/includes/form.inc \form_get_options()
2. 6 includes/form.inc \form_get_options()
3. 7 includes/form.inc \form_get_options()
4. 9 core/includes/form.inc \form_get_options()

Traverses a select element's #option array looking for any values that hold the given key. Returns an array of indexes that match.

This function is useful if you need to modify the options that are already in a form element; for example, to remove choices which are not valid because of additional filters imposed by another module. One example might be altering the choices in a taxonomy selector. To correctly handle the case of a multiple hierarchy taxonomy, #options arrays can now hold an array of objects, instead of a direct mapping of keys to labels, so that multiple choices in the selector can have the same key (and label). This makes it difficult to manipulate directly, which is why this helper function exists.

This function does not support optgroups (when the elements of the #options array are themselves arrays), and will return FALSE if arrays are found. The caller must either flatten/restore or manually do their manipulations in this case, since returning the index is not sufficient, and supporting this would make the "helper" too complicated and cumbersome to be of any help.

As usual with functions that can return array() or FALSE, do not forget to use === and !== if needed.

Parameters

$element: The select element to search.

$key: The key to look for.

Return value

An array of indexes that match the given $key. Array will be empty if no elements were found. FALSE if optgroups were found.

Related topics

File

includes/form.inc, line 1004

Code

function form_get_options($element, $key) {
  $keys = array();
  foreach ($element['#options'] as $index => $choice) {
    if (is_array($choice)) {
      return FALSE;
    }
    else {
      if (is_object($choice)) {
        if (isset($choice->option[$key])) {
          $keys[] = $index;
        }
      }
      else {
        if ($index == $key) {
          $keys[] = $index;
        }
      }
    }
  }
  return $keys;
}