1 system.module system_jump_menu($form, &$form_state, $select, $options = array())

Generate a jump menu form.

A jump menu is a select box and an optional 'go' button which can be removed if JavaScript is in use. Each item is keyed to the href that the button should go to. With JavaScript, the page is immediately redirected. Without javascript, the form is submitted and a backdrop_goto() is given.

This can either be used with backdrop_get_form() or directly added to a form. The button provides its own submit handler so by default, other submit handlers will not be called.

Do not use #tree = TRUE in jump menu forms or it will be unable to find the proper value.

$output = backdrop_get_form('system_jump_menu', $targets, $options);

Parameters

$select: An array suitable for use as the #options. The keys will be the direct URLs that will be jumped to, so you absolutely must encode these using url() in order for them to work reliably.

$options: $options may be an array with the following options:

  • 'title': The text to display for the #title attribute.
  • 'description': The text to display for the #description attribute.
  • 'default_value': The text to display for the #default_value attribute.
  • 'hide': If TRUE the go button will be set to hide via javascript and will submit on change.
  • 'button': The text to display on the button.
  • 'image': If set, an image button will be used instead, and the image set to this.
  • 'inline': If set to TRUE (default) the display will be forced inline.

File

core/modules/system/system.module, line 3353
Configuration system that lets administrators modify the workings of the site.

Code

function system_jump_menu($form, &$form_state, $select, $options = array()) {
  $options += array(
    'button' => t('Go'),
    'choose' => t('- Choose -'),
    'inline' => TRUE,
    'hide' => TRUE,
  );

  $form['#attached']['library'][] = array('system', 'jump-menu');

  if (!empty($options['choose'])) {
    $select = array('' => $options['choose']) + $select;
  }

  $form['jump'] = array(
    '#type' => 'select',
    '#options' => $select,
    '#attributes' => array(
      'class' => array('jump-menu-select'),
    ),
  );

  if (!empty($options['title'])) {
    $form['jump']['#title'] = $options['title'];
  }

  if (!empty($options['description'])) {
    $form['jump']['#description'] = $options['description'];
  }

  if (!empty($options['default_value'])) {
    $form['jump']['#default_value'] = $options['default_value'];
  }

  if (isset($options['image'])) {
    $form['go'] = array(
      '#type' => 'image_button',
      '#src' => $options['image'],
      '#submit' => array('system_jump_menu_submit'),
      '#attributes' => array(
        'class' => array('jump-menu-button'),
      ),
    );
  }
  else {
    $form['go'] = array(
      '#type' => 'submit',
      '#value' => $options['button'],
      '#submit' => array('system_jump_menu_submit'),
      '#attributes' => array(
        'class' => array('jump-menu-button'),
      ),
    );
  }

  if ($options['inline']) {
    $form['jump']['#prefix'] = '<div class="container-inline">';
    $form['go']['#suffix'] = '</div>';
  }

  if ($options['hide']) {
    $form['jump']['#attributes']['class'][] = 'jump-menu-change';
    $form['go']['#attributes']['class'][] = 'jump-menu-hide';
  }

  return $form;
}