form_get_options

Definition

form_get_options($element, $key)
includes/form.inc, line 1469

Description

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.

Name	Description
Form generation	Functions to enable the processing and display of HTML forms.

Code

<?php
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;
}
?>